@epigraph/ar
TypeScript icon, indicating that this package has built-in type declarations

2.10.6 • Public • Published

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

Quick Start with the latest stable version
<!-- include this in your `<head>` -->
<script async type="module" src='https://cdn.jsdelivr.net/npm/@epigraph/ar/dist/epigraph-ar.min.js'></script>
Quick Start with a Specific Version
<!-- 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 as an AR button
<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 as a standalone 3D viewer
<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 as a standalone 3D viewer with material variant selector
<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>
epigraph-ar as a standalone 3D viewer with material variant selector and 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 as a standalone 3D viewer with product tour
<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 with product tour and 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>
Using a slot
<epigraph-ar>
<element slot="slot-name"></element>
<epigraph-ar>
Using a CSS Shadow Part
epigraph-ar::part(part-name) {
some-rule: some-value;
}
Using a CSS Custom Property
epigraph-ar {
--some-css-property: some-new-value;
}
Listening to Events
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
arButtonRolloverNudge ar-button-rollover-nudge boolean false toggles the ability to show a

rollover nudge when the AR/QR button is hovered
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
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 orbit

each part of the string represents the following in order: roll(theta) yaw(phi) radius

this 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 measurements

imperial - uses the imperial system

metric - uses the metric system
minCameraOrbit min-camera-orbit string "auto 0deg auto" sets the minimum camera orbit

each part of the string represents the following in order: roll(theta) yaw(phi) radius

this 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 sensitivity

takes 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 viewer
TODO: 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

Package Sidebar

Install

npm i @epigraph/ar

Weekly Downloads

543

Version

2.10.6

License

Apache-2.0

Unpacked Size

2.39 MB

Total Files

7

Last publish

Collaborators

  • cpiggott
  • puneet_epigraph
  • bruno-epigraph
  • tanay-dimri