@epigraph/ar NPM

epigraph-ar

Epigraph's custom web component for AR based on Google's <model-viewer>. As such, it mostly follows their coding conventions except for public APIs. For more information, @see https://github.com/google/model-viewer/wiki/Code-conventions

Examples

<!-- include this in your `<head>` -->
<script async type="module" src='https://cdn.jsdelivr.net/npm/@epigraph/ar/dist/epigraph-ar.min.js'></script>

<!-- include this in your `<head>`, replace 2.9.0 with a specified version -->
<script async type="module" src='https://cdn.jsdelivr.net/npm/@epigraph/ar@2.9.0/dist/epigraph-ar.min.js'></script>

<epigraph-ar sku="some-valid-sku" ua-code="some-valid-ua-code" ga-measurement-id="some-valid-ga-measurement-id" ar-modes="scene-viewer quick-look"></epigraph-ar>

<epigraph-ar viewer-visible sku="some-valid-sku" ua-code="some-valid-ua-code" ga-measurement-id="some-valid-ga-measurement-id" button-mode="none"></epigraph-ar>

<epigraph-ar viewer-visible sku="some-valid-sku" ua-code="some-valid-ua-code" ga-measurement-id="some-valid-ga-measurement-id" button-mode="none" material-variant-selector-visible></epigraph-ar>

<!-- NOTE: only supported on Android Devices compatible with WebXR -->
<epigraph-ar viewer-visible sku="some-valid-sku" ua-code="some-valid-ua-code" ga-measurement-id="some-valid-ga-measurement-id" ar-modes="webxr scene-viewer quick-look" material-variant-selector-visible></epigraph-ar>

<epigraph-ar viewer-visible sku="some-valid-sku" ua-code="some-valid-ua-code" ga-measurement-id="some-valid-ga-measurement-id" button-mode="none" product-tour-visible></epigraph-ar>

<epigraph-ar viewer-visible sku="some-valid-sku" ua-code="some-valid-ua-code" ga-measurement-id="some-valid-ga-measurement-id" product-tour-visible></epigraph-ar>

<epigraph-ar>
<element slot="slot-name"></element>
<epigraph-ar>

epigraph-ar::part(part-name) {
some-rule: some-value;
}

epigraph-ar {
--some-css-property: some-new-value;
}

const epigraphAR = document.querySelector('epigraph-ar');

epigraphAR.addEventListener('event-name', () => {
doSomething();
})

Properties

Property	Attribute	Modifiers	Type	Default	Description
`arButtonModeAttribute`	`button-mode`		`string`	"mobile desktop"	sets ar button modes for the ar-button, maps to the enumerationempty string - NONEmobile - MOBILEdesktop - DESKTOPmobile desktop - BOTH
`arButtonRolloverNudge`	`ar-button-rollover-nudge`		`boolean`	false	toggles the ability to show arollover nudge when the AR/QR button is hovered
`arModes`	`ar-modes`		`string`	"scene-viewer quick-look"	sets ar modes for the ar experiencewebxr/scene-viewer - androidquick-look - iOS
`arPlacement`	`ar-placement`		`string`	"floor"	sets ar placement for the ar experiencefloor - place ar object on the floorwall - place ar object on the wall
`autoStart`	`auto-start`		`boolean`	false	used to load the 3D viewer automatically on desktop
`cameraOrbit`	`camera-orbit`		`string`	"55deg 69deg auto"	sets the viewer camera orbit values
`canActivateAR`		readonly			public method to get ar-capability status
`environmentImage`	`environment-image`		`string`	"neutral"	sets environmental lightingempty string - default scene optimized for load speedneutral - applies even lighting on all sidesHDR Image - supply HDR Image source url to this to apply custom lighting
`gaEventLabelType`	`ga-event-label-type`		`string`	"name"	flag to use different values for GA event labelname - use product name or hotspot feature namesku - use product skuname and sku - use '{name} - {sku}'sku and name - use '{sku} - {name}'
`interactionPromptThreshold`	`interaction-prompt-threshold`		`number`	3000	flag to toggle UserWithArSupport/UserWithQrSupport GA event reporting
`internalMeasurementsVisible`	`internal-measurements-visible`		`boolean`	false	sets visibility of internal model measurements
`materialVariantSelectorVisible`	`material-variant-selector-visible`		`boolean`	false	sets visibility of material variant selector
`maxCameraOrbit`	`max-camera-orbit`		`string`	"auto 100deg auto"	sets the maximum camera orbiteach part of the string represents the following in order: roll(theta) yaw(phi) radiusthis uses Euler angles @see https://en.wikipedia.org/wiki/Euler_angles#Proper_Euler_angles_2 for more information
`measurementUnit`	`measurement-unit`		`string`	"imperial"	sets which measurement system to use for internal measurementsimperial - uses the imperial systemmetric - uses the metric system
`minCameraOrbit`	`min-camera-orbit`		`string`	"auto 0deg auto"	sets the minimum camera orbiteach part of the string represents the following in order: roll(theta) yaw(phi) radiusthis uses Euler angles @see https://en.wikipedia.org/wiki/Euler_angles#Proper_Euler_angles_2 for more information
`name`			`string`	"EPIGRAPH-AR"	name to be used for the internal logging service
`orbitSensitivity`	`orbit-sensitivity`		`number`	"1"	sets the orbit sensitivitytakes any number, negative values reverse orbit
`posterBackground`	`poster`		`string`	""	sets the source url for the poster background
`posterForeground`	`poster-foreground`		`string`	""	sets the source url for the icon to display on top of the poster
`mobilePosterForeground`	`mobile-poster-foreground`		`string`	""	sets the source url for the icon to display on top of the poster on mobile devices, defaults to the value of poster-foreground if none are provided
`productTourVisible`	`product-tour-visible`		`boolean`	false	sets visibility of product tour
`shadowIntensity`	`shadow-intensity`		`number`	1	modifies the shadow intensity of the model
`showPosterOnClose`	`show-poster-on-close`		`boolean`	false	sets ability to reset model-viewer to poster upon closing fullscreen
`sku`	`sku`		`string`	""	to be used with epigraph product skus
`stopTouchPropagation`	`stop-touch-propagation`		`boolean`	false	modifies whether touch events on the 3D viewer are allowed to propagate
`theme`	`theme`		`string`	"default"	used to indicate UI/UX themes
`uaCode`	`ua-code`		`string`	""	to be used with client ua-code
`gaMeasurementId`	`ga-measurement-id`		`string`	""	to be used with client ga-measurement-id
`verboseLogging`	`verbose-logging`		`boolean`	false	used to log debugging information
`viewerVisible`	`viewer-visible`		`boolean`	false	sets visibility of the 3D viewerTODO: set a
method call to toggle this property based on response from mediator
`disableMobileFullscreen`	`disable-mobile-fullscreen`		`boolean`	false	used to disable fullscreen on mobile devices

Methods

Method	Type	Description
`dismissPoster`	`(): void`	public method to dismiss viewer poster
`showPoster`	`(): void`	public method to show viewer poster
`closeModal`	`(): void`	public method to close iOS fullscreen modal
`launchFullscreen`	`(): void`	public method to open fullscreen or fullscreen modal

Events

Event	Type	Description
`epigraph-ar-capability-determined`	`CustomEvent<{ canActivateAr: any; }>`	custom event to indicate whether the device is AR capable
`epigraph-ar-loading-error`	`CustomEvent<{ message: any; stack: any; }>`	custom event to bubble up the model load error event from model-viewer, inheriting message and stack
`epigraph-ar-model-loaded`		custom event to bubble up the model loaded event from model-viewer
`epigraph-experience-type`	`CustomEvent<ExperienceDetails>`	custom event to detail what experience is currently being rendered
`epigraph-invalid-product`		custom event to indicate product associated with the sku is invalid
`epigraph-valid-product`		custom event to indicate product associated with the sku is valid
`epigraph-ar-poster-dismissed`		custom event to indicate when the model-viewer poster is dismissed
`epigraph-ar-fullscreen-opened`		custom event to indicate when fullscreen is opened on the model-viewer
`epigraph-ar-fullscreen-close`		custom event to indicate when fullscreen is closed on the model-viewer
`epigraph-modal-opened`		custom event to indicate when the ios fullscreen modal is opened
`epigraph-modal-close`		custom event to indicate when the ios fullscreen modal is closed

Slots

Name	Description
`ar-button`	replaces the ar-button but maintains the onclick function
`ar-button-rollover-nudge`	replaces the rollover nudge that appears onhover, if enabled
`mobile-product-tour-button`	replaces the mobile product tour launch button
`poster`	replaces the viewer poster
`poster-foreground`	replaces the poster icon
`mobile-poster-foreground`	replaces the mobile poster icon
`progress-bar`	replaces the progress indicator
`qr-modal-close`	replaces the qr-modal close button
`qr-modal-done`	replaces the qr-modal done button
`qr-modal-instruction`	replaces the qr-modal instruction
`qr-modal-requirement`	replaces the qr-modal requirement
`qr-modal-title`	replaces the qr-modal title
`viewer-modal-exit-button`	replaces the button that exits the fullscreen viewer

CSS Shadow Parts

Part	Description
`ar-button-container`	points to the ar button container
`ar-button-rollover-nudge`	points to the rollover nudge that displays on hover
`default-ar-button`	points to the default ar button
`default-poster-foreground`	points to the default poster icon
`default-poster-background`	points to the default poster background
`default-poster-background-image`	points to the default poster background image
`hotspot-button`	points to the hotspot buttons
`hotspot-button-annotation`	points to the hotspot button annotation
`hotspot-button-inner-circle`	points to the inner circle of the hotspot button
`material-variant-selector`	points to the `<material-variant-selector>` element
`material-variant-selector-button`	points to the selector buttons themselves
`material-variant-selector-container`	points to the container housing the selectors
`mobile-product-tour-button-default`	points to the default mobile product tour launch button
`model-viewer`	points to the `<model-viewer>` element
`poster-foreground`	points to the poster icon
`poster-foreground-image`	points to the poster icon image
`mobile-poster-foreground`	points to the mobile poster icon
`mobile-poster-foreground-image`	points to the mobile poster icon image
`product-tour`	points to the `<product-tour>` element
`product-tour-carousel-media`	points to the media housed inside media carousels
`product-tour-close-container`	points to the side panel close button container
`product-tour-close-default`	points to the side panel default close button
`product-tour-container`	points to the side panel container
`product-tour-feature-content-container`	points to the side panel feature content containers
`product-tour-feature-description`	points to the description of the feature text
`product-tour-feature-media-container`	points to the containers housing feature media
`product-tour-feature-text-container`	points to the container housing the feature text
`product-tour-feature-title`	points to the title of the feature text
`product-tour-inner-content-container`	points to the side panel inner content container
`product-tour-media-carousel`	points to the feature media carousels
`product-tour-media-carousel-dot`	points to the control buttons for the media carousels
`product-tour-media-controls-container`	points to the containers housing the control buttons for the media carousels
`product-tour-media-title`	points to the feature media titles
`qr-modal`	points to the `<qr-modal>` element
`qr-modal-background`	points to the modal background
`qr-modal-close-default`	points to the default close button in the qr-modal
`qr-modal-container`	points to the main modal
`qr-modal-done-default`	points to the default done button in the qr-modal
`qr-modal-instruction-default`	points to the default instruction in the qr-modal
`qr-modal-qr-container`	points to the qr container within the qr-modal
`qr-modal-qr-image`	points to the qr image in the modal
`qr-modal-requirement-default`	points to the default requirement in the qr-modal
`qr-modal-title-default`	points to the default title in the qr-modal
`viewer-modal-exit-button`	points to the button that exits the fullscreen viewer on mobile
`webxr-banner`	points to the webxr banner
`webxr-banner-name`	points to the product name in the text portion
`webxr-banner-pdp`	points to the the url text below the name in the text portion
`webxr-banner-text`	points to the text portion of the webxr banner
`webxr-banner-visit-button`	points to the visit button in the banner

CSS Custom Properties

Property	Description
`--ar-button-active-background-color`	edits ar-button background color when clicked
`--ar-button-background-color`	edits ar-button background color
`--ar-button-border-color`	edits ar-button border color
`--ar-button-hover-background-color`	edits ar-button background color when hovered
`--ar-button-hover-text-color`	edits ar-button text color when hovered
`--ar-button-text-color`	edits ar-button text color
`--ar-icon-frame-color`	edits ar-icon frame color
`--ar-icon-hover-frame-color`	edits ar-icon frame color when hovered
`--ar-icon-hover-vector-1-color`	edits ar-icon vector 1 color when hovered
`--ar-icon-hover-vector-2-color`	edits ar-icon vector 2 color when hovered
`--ar-icon-hover-vector-3-color`	edits ar-icon vector 3 color when hovered
`--ar-icon-vector-1-color`	edits ar-icon vector 1 (top face) color
`--ar-icon-vector-2-color`	edits ar-icon vector 2 (left face) color
`--ar-icon-vector-3-color`	edits ar-icon vector 3 (right face) color
`--hotspot-button-background-color`	edits hotspot button background color
`--hotspot-button-border-color`	edits hotspot button border color
`--hotspot-button-focus-border-color`	edits hotspot button border color when focused
`--hotspot-inner-circle-border-color`	edits hotspot button inner circle border color
`--hotspot-inner-circle-viewed-border-color`	edits hotspot button inner circle border color when viewed
`--mobile-product-tour-button-background-color`	edits product-tour mobile button background color
`--mobile-product-tour-button-text-color`	edits product-tour mobile button text color
`--product-tour-background-color`	edits product-tour background color
`--product-tour-close-button-fill-color`	edits product-tour close button fill color
`--product-tour-close-button-hover-fill-color`	edits product-tour close button fill color when hovered
`--product-tour-close-button-hover-stroke-color`	edits product-tour close-button stroke color when hovered
`--product-tour-close-button-stroke-color`	edits product-tour close-button stroke color
`--product-tour-current-dot-background-color`	edits product-tour control dot background color when it points to a current image
`--product-tour-dot-background-color`	edits product-tour control dot background color
`--model-viewer-mobile-close-button-outline-color`	edits product-tour mobile close button outline color
`--model-viewer-mobile-close-button-stroke-color`	edits product-tour mobile close button stroke color
`--progress-ring-color`	edits the progress ring color
`--progress-ring-radius`	edits the progress ring radius
`--progress-ring-thickness`	edits the progress ring thickness
`--qr-modal-close-button-stroke-color`	edits qr-modal close button stroke color
`--qr-modal-done-button-active-background-color`	edits qr-modal done button background color when clicked
`--qr-modal-done-button-background-color`	edits qr-modal done button background color
`--qr-modal-done-button-border-color`	edits qr-modal done button border color
`--qr-modal-done-button-hover-background-color`	edits qr-modal done button background color when hovered
`--qr-modal-done-button-hover-text-color`	edits qr-modal done button text color when hovered
`--qr-modal-done-button-text-color`	edits qr-modal done button text color
`--qr-modal-instruction-color`	edits qr-modal instruction text color
`--qr-modal-requirement-color`	edits qr-modal requirement text color
`--qr-modal-title-color`	edits qr-modal title text color