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://unpkg.com/%40epigraph/ar/dist/epigraph-ar.min.js'></script>
<!-- include this in your `<head>`, replace version-number with a specified version -->
<script async type="module" src='https://unpkg.com/%40epigraph/ar%40{version-number}/dist/epigraph-ar.min.js'></script>
<epigraph-ar sku="some-valid-sku" ua-code="some-valid-ua-code" ar-modes="scene-viewer quick-look"></epigraph-ar>
<epigraph-ar viewer-visible sku="some-valid-sku" ua-code="some-valid-ua-code" button-mode="none"></epigraph-ar>
<epigraph-ar viewer-visible sku="some-valid-sku" ua-code="some-valid-ua-code" 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" 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" button-mode="none" product-tour-visible></epigraph-ar>
<epigraph-ar viewer-visible sku="some-valid-sku" ua-code="some-valid-ua-code" 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 enumeration empty string - NONE mobile - MOBILE desktop - DESKTOP mobile desktop - BOTH |
|
arModes |
ar-modes |
string |
"scene-viewer quick-look" | sets ar modes for the ar experience webxr/scene-viewer - android quick-look - iOS |
|
arPlacement |
ar-placement |
string |
"floor" | sets ar placement for the ar experience floor - place ar object on the floor wall - 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 lighting empty string - default scene optimized for load speed neutral - applies even lighting on all sides HDR 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 label name - use product name or hotspot feature name sku - use product sku name 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 | |
materialVariantSelectorVisible |
material-variant-selector-visible |
boolean |
false | sets visibility of material variant selector | |
name |
string |
"EPIGRAPH-AR" | name to be used for the internal logging service | ||
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 | |
productTourVisible |
product-tour-visible |
boolean |
false | sets visibility of product tour | |
shadowIntensity |
shadow-intensity |
number |
1 | modifies the shadow intensity of the model | |
sku |
sku |
string |
"" | to be used with epigraph product skus | |
theme |
theme |
string |
"default" | used to indicate UI/UX themes | |
uaCode |
ua-code |
string |
"" | to be used with client ua-code | |
verboseLogging |
verbose-logging |
boolean |
false | used to log debugging information | |
viewerVisible |
viewer-visible |
boolean |
false | sets visibility of the 3D viewer TODO: set a method call to toggle this property based on response from mediator |
Methods
| Method | Type | Description |
|---|---|---|
dismissPoster |
(): void |
public method to dismiss viewer poster |
showPoster |
(): void |
public method to show viewer poster |
Events
| Event | Type | Description |
|---|---|---|
epigraph-ar-capability-determined |
CustomEvent<{ canActivateAr: any; }> |
custom event to indicate whether the device is AR capable |
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 |
Slots
| Name | Description |
|---|---|
ar-button |
replaces the ar-button but maintains the onclick function |
mobile-product-tour-button |
replaces the mobile product tour launch button |
poster |
replaces the viewer poster |
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 |
CSS Shadow Parts
| Part | Description |
|---|---|
ar-button-container |
points to the ar button container |
default-ar-button |
points to the default ar button |
default-poster-background |
points to the default poster background |
default-poster-foreground |
points to the default poster icon |
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 |
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 |
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 |
--product-tour-mobile-close-button-outline-color |
edits product-tour mobile close button outline color |
--product-tour-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 |