@epigraph/ar
v2.10.9
Published
The Epigraph AR web component
Downloads
2,721
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 |