This guide should not be used if you have a WordPress website.
There are many situations in which you will want to trigger push notifications to your users, here are some examples:
- Private message has been received
- An order has been delivered
- A new file has been added to the account
- A subscription is about to expire
For all of these examples, the notification will need to target a specific user when a specific action or event happens on your website. In order to be able to send these notifications you will need the following implemented into your website's code:
- OneSignal REST API
- Canvas native functions
Keep in mind that this is not an implementation guide for the OneSignal REST API, each server and website is different and will require a developer to find the best approach for implementing the push notification code. The purpose of this guide is to give you a better understanding of how to integrate your website with the Canvas platform for sending targeted and personalized push notifications.
Let's go through each one of the requirements:
OneSignal REST API
Since Canvas uses OneSignal for push notifications, you will need to use the OneSignal REST API to trigger the notifications.
Whenever a push notification is expected to be sent, you will need to make a call to the OneSignal REST API with the notification details (title, text, link, image, tags, etc).
Here you can find the complete documentation for the OneSignal REST API: https://documentation.onesignal.com/reference/create-notification
Canvas native functions
Implementing the OneSignal REST API should be straightforward, but at some point, you will ask yourself "How do I target a specific user?", and that's where the Canvas native functions come into play.
On your website, you are probably using a unique ID or even an email to identify your users, but in OneSignal that unique identifier is not available out of the box, so the idea here is to tell OneSignal to store the same unique user ID from your website into the OneSignal profile of that user.
To do this, we are going to trigger the following Javascript function as soon as the user has logged in:
<script type="text/javascript">
// Check the user agent for the "canvas" string
const isApp = navigator.userAgent.toLowerCase().indexOf('canvas') > -1;
// Add the event listener
window.addEventListener("message", (event) => {
runNativeFunctions(event);
}, false);
// Run when the event listener is triggered
function runNativeFunctions(event) {
try {
// Check if we are in the app
if (isApp) {
// If we have the app confirmation to use native functions
if (event.data && event.data == 'nativeFunctionsLoaded') {
// Set the external user ID
let externalUserId = 1;
// Trigger the native function to save to OneSignal
nativeFunctions.onesignalSetExternalUserId(externalUserId);
// Log the event in the console
console.log("External user ID set");
}
}
} catch (ex) {
console.log(ex.message;);
}
}
</script>
The nativeFunctions.onesignalSetExternalUserId function will tell the app to make a request to OneSignal and set the provided ID as the External User ID for the current device, which will allow you to target that specific user in your notifications using the exact identifier that you use on your website.
We recommend adding the Javascript code inline rather than using a separate file, to avoid compatibility issues.
For more details on how to target users using the External User ID, you can refer to the OneSignal documentation here: https://documentation.onesignal.com/docs/external-user-ids
You can also find a list of all available native functions here: https://www.mobiloud.com/help/knowledge-base/how-to-use-canvas-functions
