When you embed a Dot.vu interactive experience on your website, the Dot.vu tag you install provides a client side API that among other things, allows you to handle loading errors, to mitigate bad user experiences.
Why Error Handling
Let’s suppose you have an interactive experience that is LIVE and embedded on your website, and then you or another admin of your account mistakenly puts that experience offline from the Dot.vu dashboard.
At this point, you are still attempting to embed the experience on your site because the tag script is there, but the experience is offline. This leads to an error while loading.
Furthermore, if a user loses internet connection while your webpage is loading or in the unlikely event of service unavailability, a loading error will also occur.
So when a loading error occurs, you will probably want to inform and/or redirect users to keep them engaged, and you may as well log the issue for your own awareness and resolution.
Q: What If I don’t Handle Errors?
Let’s say you’re optimistic or perhaps low on resources or time to setup error handlers.
You should at least know that if an error occurs while attempting to load and embed an interactive experience:
- The placeholder for the experience will be blank (empty)
- No information or content will be shown or provided to the user
An error will be shown on the browsers console, if you have the browser’s developer tools opened. Here’s an example:
e: The requested experience does not exist or has been deleted.So the downsides of not handling errors are:
- Users will see a blank area where the experience would have been, when they arrive on your webpage
- You lose awareness by not logging the issue
How To Handle Errors
Important: Here we get a bit technical, so if you would like to setup error handling but are unfamiliar with web technologies, just refer this article to your IT or developer team.
A Dot.vu Project Tag is a piece of mostly JavaScript code that loads and initializes the dot.js library, and finally loads an experience.
Library Loading Error
In the unlikely event of the dot.js library itself failing to load – due to network issues such as no internet connection, or DNS resolution on a private network, or service unavailability – you can add a callback error handling function as an onerror property of the last argument of the first function in the tag. See below, where the code added is in bold:
!function(d,o,t,v,u){var l="dataLayer";d[v]=d[v]||function(){(d[v][l]=d[v][l]||[]).push.apply(d[v][l],arguments)},d[v][l]=d[v][l]||[];var s=o.createElement(t),f=o.getElementsByTagName(t)[0];for(var k in u)Object.prototype.hasOwnProperty.call(u,k)&&(s[k]=u[k]);f&&f.parentNode?f.parentNode.insertBefore(s,f):o.head.appendChild(s)}(window,document,"script","dotVu",{async:!0,src:"https://cdn.dot.vu/core/dot.js", onerror: function() { /** handle library loading error */} });
window["dotVu"]({ eventType: "init", accountId: "123" });
This onerror callback function will receive an error argument.
Experience Loading Errors
Once the library is loaded and initialized, experiences can then be embedded, and you can handle any experience loading errors by configuring a callback property on the details object of the projectLoad event. See below in bold:
window["dotVu"]({
eventType: "projectLoad",
accountId: "123",
details: {
"config": { ... },
"options": { ... },
"callback": function(error, page) {
if(error) {
switch(error.code) {
case 'EXPERIENCE_IS_OFFLINE':
// handle experience is offline error
break;
case 'EXPERIENCE_NOT_FOUND':
// handle experience not found error
break;
case 'EXPERIENCE_LOAD_TIMEOUT':
// handle loading timeout error
break;
default:
// handle eventual unknown errors
break;
}
} else if(page) {
// experience page is loaded
}
}
}
});
The callback is a function that receives an error as first argument when there is an experience loading error (otherwise null), or the page as second argument on successful loading.
Did you know? You can communicate between your website and its interactive experiences? The same callback function can be used for securely sending and receiving information to an embedded experience.
Loading Timeout
You can set a specific timeout so that an error is thrown if an experience takes longer to load than specified. This value is by default 30 seconds.
You can set a default timeout for all your experiences by providing a defaultTimeout property with a number value (in milliseconds), on the init event’s details object, like this:
window["dotVu"]({
eventType: "init",
accountId: "123",
details: {
defaultTimeout: 5000 // in milliseconds
}
});
And/or you can specify the timeout per project, in which case you add a timeout property with a number value (in milliseconds), on the projectLoad event’s details object, like this:
window["dotVu"]({
eventType: "projectLoad",
accountId: "123",
details: {
"config": { ... },
"options": { ... },
"timeout": 5000, // in milliseconds
"callback": function(error, page) {
if(error) {
// handle errors
} else if(page) {
// experience page is loaded
}
}
}
});
If you have set a defaultTimeout on the init event, any timeout value you set on a projectLoad event will overwrite the default timeout for that specific project load.
Important. Make sure to set an appropriate timeout for your experiences! Some experiences are lightweight and can load in under two seconds; however, experiences which contain a lot of interactive content, like an Interactive Flipbook, may take longer to load. Additionally, remember that loading speeds are affected by the user’s connection quality and the device they are using.
Experience Loading Errors
| Property | Type |
| code | ‘EXPERIENCE_IS_OFFLINE’ |
| name | ‘ApiError’ |
| message | string |
| status | 404 |
| Property | Type |
| code | ‘EXPERIENCE_NOT_FOUND’ |
| name | ‘ApiError’ |
| message | string |
| status | 404 |
| Property | Type |
| code | ‘EXPERIENCE_LOAD_TIMEOUT’ |
| name | ‘TimeoutError’ |
| message | string |
| timeout | number |
| Property | Type |
| code | ‘UNKNOWN_ERROR’ |
| name | ‘UnknownError’ |
| message | string |
| details | object |