@epigraph/ar
v2.11.6
Published
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
Readme
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/[email protected]/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 |