SDK Configuration Properties
Refer various SDK config properties applicable for WebAR SDK
WebAR SDK can be configured to select the mode (surface or marker tracking), customize the logo, style of the splash screen, UI screens (shown by SDK) etc using the following SDK configuration parameters.
These parameters can be used in different ways:
Adding as properties in javascript object window.WEBAR_SDK_CONFIG. A separate script having this object defined has to be included before loading the SDK <script> tag.
Example:
webar-sdk-config.js
window.WEBAR_SDK_CONFIG = {
"webar-mode": "surface-tracking",
"rendering-engine": "playcanvas",
"auto-init": "true",
"logo-src": "../images/test_logo_here.png"
};index.html :
<script src="https://webar-sdk.blippar.com/releases/live-config/playcanvas/webar-sdk-config-surface.js"></script>
<script src="https://webar-sdk.blippar.com/releases/latest/cdn/blippar/webar-sdk-v1.2.0-beta.min.js?license-key=xxxxxxxx-1111-2222-3333-yyyyyyyyyyyy"></script>Adding as html attributes to the <script> tag in which the WebAR SDK js file is loaded.
Adding as a URL search params in the SDK script tag url.
Only the license-key property can be passed via URL search params. Passing other properties via URL will not work.
Example:
<script src="https://webar-sdk.blippar.com/releases/latest/cdn/blippar/webar-sdk-v1.2.0-beta.min.js?license-key=xxxxxxxx-1111-2222-3333-yyyyyyyyyyyy"></script>alert-background-color
Description
On iOS Safari browser, a Camera permission request notice is displayed before asking the user to allow access to the Camera. This attribute changes the background color of the notice alert dialog.
Example
<script src="path_to_webar_sdk_script.js"
progress-ring-color="#283747"
...></script>alert-border-color
Description
On iOS Safari browser, a Camera permission request notice is displayed before asking the user to allow access to the Camera. This attribute changes the border color of the notice alert dialog.
Example
<script src="path_to_webar_sdk_script.js"
progress-ring-color="5"
...></script>alert-border-width
Description
On iOS Safari browser, a Camera permission request notice is displayed before asking the user to allow access to the Camera. This attribute changes the border thickness of the notice alert dialog.
Example
<script src="path_to_webar_sdk_script.js"
progress-ring-color="5px"
...></script>alert-box-font-size
Description
On iOS Safari browser, a Camera permission request notice is displayed before asking the user to allow access to the Camera. This attribute changes the font size of the text in the notice alert dialog.
Example
<script src="path_to_webar_sdk_script.js"
alert-box-font-size="24px"
...></script>alert-box-height
Description
On iOS Safari browser, a Camera permission request notice is displayed before asking the user to allow access to the Camera. This attribute changes the height of the notice alert dialog.
Example
<script src="path_to_webar_sdk_script.js"
alert-box-height="182px"
...></script>alert-box-width
Description
On iOS Safari browser, a Camera permission request notice is displayed before asking the user to allow access to the Camera. This attribute changes the width of the notice alert dialog.
Example
<script src="path_to_webar_sdk_script.js"
alert-box-width="290px"
...></script>alert-button-color
Description
On iOS Safari browser, a Camera permission request notice is displayed before asking the user to allow access to the Camera. This attribute changes the button color in the notice alert dialog.
Example
<script src="path_to_webar_sdk_script.js"
progress-ring-color="#00FFFF"
...></script>alert-button-height
Description
On iOS Safari browser, a Camera permission request notice is displayed before asking the user to allow access to the Camera. This attribute changes the button height in the notice alert dialog.
Example
<script src="path_to_webar_sdk_script.js"
progress-ring-color="50px"
...></script>alert-button-text-color
Description
On iOS Safari browser, a Camera permission request notice is displayed before asking the user to allow access to the Camera. This attribute changes the button text color in the notice alert dialog.
Example
<script src="path_to_webar_sdk_script.js"
progress-ring-color="#283747"
...></script>alert-camera-permission-button-text
Description
On iOS Safari browser, a Camera permission request notice is displayed before asking the user to allow access to the Camera. This attribute changes the camera permission button text in the notice alert dialog.
Example
<script src="path_to_webar_sdk_script.js"
alert-motion-permission-text="No Problem"
...></script>alert-camera-permission-text
Description
On iOS Safari browser, a Camera permission request notice is displayed before asking the user to allow access to the Camera. This attribute changes the camera permission text in the notice alert dialog.
Example
<script src="path_to_webar_sdk_script.js"
alert-camera-permission-text="We need to ask for access to the camera so this experience can work!!!"
...></script>alert-message-text-color
Description
On iOS Safari browser, a Camera permission request notice is displayed before asking the user to allow access to the Camera. This attribute changes the text color in the notice alert dialog.
Example
<script src="path_to_webar_sdk_script.js"
progress-ring-color="#283747"
...></script>alert-motion-permission-button-text
Description
On iOS Safari browser, a Camera permission request notice is displayed before asking the user to allow access to the Camera. This attribute changes the motion sensor permission button text in the notice alert dialog.
Example
<script src="path_to_webar_sdk_script.js"
alert-motion-permission-text="No Problem"
...></script>alert-motion-permission-text
Description
On iOS Safari browser, a Camera permission request notice is displayed before asking the user to allow access to the Camera. This attribute changes the motion sensor permission text in the notice alert dialog.
Example
<script src="path_to_webar_sdk_script.js"
alert-motion-permission-text="Now we need access to motion sensors!!!"
...></script>auto-init
Description
When SDK and A-Frame components with webar-* attributes are loaded, the AR experience starts automatically by default. In case the AR experience has to be started only after an event or user intervention, then auto-init attribute can be set to "false".
Example
<head>auto-init
<script src="<path_to_webar_sdk_min_js>"
auto-init="false">
</script>
</head>
<body>
<script>
WEBARSDK.Init();
</script>
</body>auto-marker-detection
Description
It enables auto marker detection so that user doesn't have to manually click the scan button, rather it detects automatically when it recognises a marker.
Example
<head>auto-init
<script src="<path_to_webar_sdk_min_js>"
auto-marker-detection="true">
</script>
</head>auto-scan-instruction
Description
User can change the default scan instruction for auto marker detection, i.e. when auto-marker-detection sets to 'true'.
Example
<head>auto-init
<script src="<path_to_webar_sdk_min_js>"
auto-scan-instruction="Find a marker to scan...">
</script>
</head>auto-scan-instruction-detect
Description
User can change the default scan instruction when marker is detecting i.e. recognises a marker image.
Example
<head>auto-init
<script src="<path_to_webar_sdk_min_js>"
auto-scan-instruction-detect="Marker detecting...">
</script>
</head>auto-scan-instruction-idle
Description
User can change the default scan instruction when phone is idle
Example
<head>auto-init
<script src="<path_to_webar_sdk_min_js>"
auto-scan-instruction-idle="Shake your phone to start detection">
</script>
</head>auto-scan-instruction-text-style
Description
Changes the css style of scan instruction text element.
Example
<head>auto-init
<script src="<path_to_webar_sdk_min_js>"
auto-scan-instruction-text-style="color: orange">
</script>
</head>auto-scan-style
Description
User can change css style of scan instruction html element.
Example
<head>auto-init
<script src="<path_to_webar_sdk_min_js>"
auto-scan-style=""display: none; position: absolute; top: 90%; left: 50%; transform: translate(-50%, -50%); z-index: 10000; width: auto; height: auto; text-align: center;"">
</script>
</head>auto-scan-style-display
Description
User can change the display style of auto scan html element
Example
<head>auto-init
<script src="<path_to_webar_sdk_min_js>"
auto-scan-style-display="display: block">
</script>
</head>auto-start
Description
When sdk and A-Frame components with webar-* attributes are loaded, the AR experience starts automatically by default. In case the AR experience has to be started only after an event or user intervention, then the auto-start attribute can be set to "false".
Example
<head>auto-init
<script src="<path_to_webar_sdk_min_js>"
auto-start="false">
</script>
</head>
<body>
<script>
WEBARSDK.StartTracking();
</script>
</body>desktop-logo-height / desktop-logo-width
Description
Changes the height and width of the logo image displayed in a desktop browser where the user is asked to scan the QR code or type the url in Android or iOS mobile browsers.
Example
<script src="path_to_webar_sdk_script.js"
desktop-logo-height="30px"
desktop-logo-width="108px"
...></script>desktop-logo-src
Description
Changes the logo image displayed in a desktop browser where the user is asked to scan the QR code or type the url in Android or iOS mobile browsers.
Example
<script src="path_to_webar_sdk_script.js"
desktop-logo-src="images/my_rectangular_logo.png"
...></script>issue-img-height / issue-img-width
Description
Changes the height and width of the warning symbol image displayed in the landscape warning screen, or any device/server communication error.
Example
<script src="path_to_webar_sdk_script.js"
issue-img-height="116px"
issue-img-width="116px"
...></script> issue-img-src
Description
Changes the warning symbol image displayed in the landscape warning screen, or any device or server communication error.
Example
<script src="path_to_webar_sdk_script.js"
issue-img-src="images/my_exclamation_image.png"
...></script>logo-height / logo-width
Description
Changes the height and width of the circular logo in the loading splash screen.
Example
<script src="path_to_webar_sdk_script.js"
logo-height="116px"
logo-width="116px"
...></script>logo-src
Description
Changes the circular logo in the loading splash screen.
Example
<script src="path_to_webar_sdk_script.js"
logo-src="images/my_logo.png"
...></script>on-load
Description
Loads a custom splash screen. To create a custom splash screen, the user should create a function and pass the function as a string to the "on-load" attribute.
Example
<script type="text/javascript">
function SetMySplash() {
let splashDiv = document.createElement('div');
splashDiv.setAttribute('id',"mySplash");
splashDiv.setAttribute('style',"background-color: black; position: absolute; align-items: center; justify-content: center; top: 0; bottom: -1px; left: 0; right: 0; min-width: 100vw; min-height: 100vh; width: auto; height: auto; margin: auto; z-index: 2; user-select: none; -webkit-user-select: none; -moz-user-select: none;");
let logoImg = document.createElement('img');
const progress = WEBARSDK.GetLoadingProgress();
...
document.body.append(splashDiv);
}
</script>
<script src="path_to_webar_sdk_script.js"
on-load="SetMySplash()"
...></script>progress-dot-ring-color
Description
Changes the color of the dotted loading ring which runs indefinitely until the splash screen disappears.
Example
<script src="path_to_webar_sdk_script.js"
progress-dot-ring-color="#00AAFF"
...></script>progress-dot-ring-scale
Description
Changes the size/scale of the dotted loading ring which runs indefinitely until the splash screen disappears.
Example
<script src="path_to_webar_sdk_script.js"
progress-dot-ring-scale="0.30"
...></script>progress-ring-color
Description
Changes the color of the loading progress update ring.
Example
<script src="path_to_webar_sdk_script.js"
progress-ring-color="#00FFFF"
...></script>progress-ring-line-width
Description
Changes the thickness of the loading progress update ring.
Example
<script src="path_to_webar_sdk_script.js"
progress-ring-color="5"
...></script>progress-ring-scale
Description
Changes the size of the loading progress update ring.
Example
<script src="path_to_webar_sdk_script.js"
progress-ring-scale="0.36"
...></script>rendering-engine
Description
Decides which rendering engine is to be used with the application
babylonjs
BabylonJS rendering engine
playcanvas
Playcanvas rendering engine
aframe
(Default) AFrame rendering engine.
By default the AFrame rendering engine is chosen by sdk even in the following cases:
If the rendering-engine attribute is not specified in the sdk script tag
If the rendering-engine attribute is specified but the value does not match the supported values
Example
<head>
<script src="<path_to_webar_sdk_min_js>"
rendering-engine="babylonjs">
</script>
</head>
<body>
<script>
WEBARSDK.Init();
</script>
</body>scan-btn-display
Description
Changes the css display property of the scan button displayed during marker tracking i.e. when webar-mode="marker-tracking". To make it invisible set it to "none" else "block".
Example
<script src="path_to_webar_sdk_script.js"
scan-btn-display="block"
...></script>scan-btn-height / scan-btn-width
Description
Changes the height and width of the scan button displayed during marker tracking i.e. when webar-mode="marker-tracking".
Example
<script src="path_to_webar_sdk_script.js"
scan-btn-height="100px"
scan-btn-width="100px"
...></script> scan-btn-img-height / scan-btn-img-width
Description
Sets the height and width of the image displayed in the scan button displayed during marker tracking i.e. when webar-mode="marker-tracking".
Example
<script src="path_to_webar_sdk_script.js"
scan-btn-img-height="50"
scan-btn-img-width="50"
...></script>scan-btn-img-src
Description
Sets the image of the scan button displayed during marker tracking i.e. when webar-mode="marker-tracking".
Example
<script src="path_to_webar_sdk_script.js"
scan-btn-img-src="images/user_scan-btn-image_here.png"
...></script>scan-btn-img-transform
Description
Sets the SVG transform property (e.g. translate(), rotate() etc.) of the image displayed in the scan button displayed during marker tracking i.e. when webar-mode="marker-tracking".
Example
<script src="path_to_webar_sdk_script.js"
scan-btn-img-transform="translate(-25, -25)"
...></script>scan-btn-img-x-coordinate / scan-btn-img-y-coordinate
Description
Sets the x and y coordinates of the image displayed in the scan button during marker tracking i.e. when webar-mode="marker-tracking". The x and y position of the image is the top left position, relative to the viewport of the origin of the element i.e the scan button. Use scan-btn-img-transform attribute's translate() method to position the image to the centre.
Example
<script src="path_to_webar_sdk_script.js"
scan-btn-img-x-coordinate="50%"
scan-btn-img-y-coordinate="50%"
...></script>scan-btn-instruction
Description
Changes the text below the scan button displayed during marker tracking i.e. when webar-mode="marker-tracking".
Example
<script src="path_to_webar_sdk_script.js"
scan-btn-instruction="Tap to scan"
...></script>scan-btn-instruction-style
Description
Changes the css style of the text below the scan button displayed during marker tracking i.e. when webar-mode="marker-tracking".
Example
<script src="path_to_webar_sdk_script.js"
scan-btn-instruction-style="color: white;"
...></script>scan-btn-progress-bar-color
Description
Sets the color of the progress foreground circular bar displayed around the scan button during marker tracking i.e. when webar-mode="marker-tracking".
Example
<script src="path_to_webar_sdk_script.js"
scan-btn-progress-bar-color="blue"
...></script>scan-btn-progress-bar-cx-coordinate / scan-btn-progress-bar-cy-coordinate
Description
Sets the x and y coordinates of the centre of the progress foreground circular bar displayed around the scan button during marker tracking i.e. when webar-mode="marker-tracking".
Example
<script src="path_to_webar_sdk_script.js"
scan-btn-progress-bar-cx-coordinate="50"
scan-btn-progress-bar-cy-coordinate="50"
...></script>scan-btn-progress-bar-radius
Description
Sets the radius of the progress foreground circular bar displayed around the scan button during marker tracking i.e. when webar-mode="marker-tracking".
Example
<script src="path_to_webar_sdk_script.js"
scan-btn-progress-bar-radius="35"
...></script>scan-btn-progress-bar-transform
Description
Sets the SVG transform property (e.g. translate(), rotate() etc.) of the progress foreground circular bar displayed around the scan button during marker tracking i.e. when webar-mode="marker-tracking".
Example
<script src="path_to_webar_sdk_script.js"
scan-btn-progress-bar-transform="rotate(-90 50 50)"
...></script>scan-btn-progress-circle-cx-coordinate / scan-btn-progress-circle-cy-coordinate
Description
Sets the x and y coordinates of the centre point of the progress background circle displayed around the scan button during marker tracking i.e. when webar-mode="marker-tracking".
Example
<script src="path_to_webar_sdk_script.js"
scan-btn-progress-circle-cx-coordinate="50%"
scan-btn-progress-circle-cy-coordinate="50%"
...></script>scan-btn-progress-circle-radius
Description
Sets the radius of the progress background circle displayed around the scan button during marker tracking i.e. when webar-mode="marker-tracking".
Example
<script src="path_to_webar_sdk_script.js"
scan-btn-progress-circle-radius="35"
...></script>scan-btn-progress-circle-style
Description
Sets the SVG style of the progress background circle displayed around the scan button during marker tracking i.e. when webar-mode="marker-tracking".
Example
<script src="path_to_webar_sdk_script.js"
scan-btn-progress-circle-style="fill: none; stroke: cyan; stroke-width: 6;"
...></script>show-guide-view
Description
Enable or disable displaying the default Hand with phone animation guide, which instructs the user to move the phone left and right to detect a surface.
Example
<script src="path_to_webar_sdk_script.js"
show-guide-view="false"
...></script>show-guide-animation-url
Description
Sets the custom animation URL for hand guide animation of surface tracking. Please note that it only supports lottie animations json format.(https://lottiefiles.com)
Example
<script src="path_to_webar_sdk_script.js"
show-guide-animation-url="https://assets4.lottiefiles.com/packages/lf20_lir7pmho.json"
...></script>static-camera
Description
By default, sdk assumes Static-Camera-With-A-Moving-Stage i.e. 'static-camera' = 'true'. However, it can be changed to Moving-Camera-With-A-Static-Stage by setting 'static-camera' = 'false'.
Example
<scriptsrc="path_to_webar_sdk_script.js"
static-camera="true"
...></script>ui-background-color
Description
Changes the background color of the loading splash screen, landscape warning screen or any device/server communication error.
Example
<script src="path_to_webar_sdk_script.js"
progress-ring-color="#283747"
...></script>ui-portrait-text
Description
Replaces the default text shown in the landscape warning screen.
Example
<script src="path_to_webar_sdk_script.js"
ui-portrait-text="Cette expérience est conçue pour le mode Portrait uniquement"
...></script>ui-text-color
Description
Changes the text color of the landscape warning screen, or any device/server communication error.
Example
<script src="path_to_webar_sdk_script.js"
progress-ring-color="#00FFFF"
...></script>webar-mode
Description
Decides whether to run the WebAR SDK in Surface Tracking or Image/Marker Tracking mode.
surface-tracking
Runs the WebAR SDK in Surface Tracking mode. Surface Tracking is the default mode. If this attribute is not present or any other not-supported value is provided, it runs in Surface Tracking mode.
In surface tracking mode, the <a-scene webar-scene> should have one <a-entity webar-stage> element. See webar-stage (A-frame) attribute for more details.
marker-tracking
Runs the WebAR SDK in Marker Tracking mode.
lazy-mode
Runs the WebAR SDK in Lazy Mode i.e. allows the user to decide at a later stage which tracking should be enabled. The user can set the respective tracking mode using functionSetWebARMode("tracking-mode"), see the example below.
Example
Without Lazy Mode
<head>
<script src="<path_to_webar_sdk_min_js>"
webar-mode="marker-tracking">
</script>
</head>
<body>
<script>
WEBARSDK.Init();
</script>
</body>With Lazy Mode
<head>
<script src="<path_to_webar_sdk_min_js>"
webar-mode="lazy-mode">
</script>
</head>
<body>
<script>
WEBARSDK.SetWebARMode("surface-tracking");
</script>
</body>Playcanvas Customization
For PlayCanvas customization, kindly use the following config files which can be found at playcanvas/config folder in the downloaded SDK zip file:
webar-sdk-config-surface.js
webar-sdk-config-marker.js
These files have to be modified and hosted on a separate server (say my-server.com) and the url has to be overwritten in the Playcanvas project.
Process:
Login to Playcanvas and navigate to Settings> External Scripts > first url entry as shown below and replace the first url with your custom config url.
Last updated