Integrate OneSignal with your website

⚠️ 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:

• A 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 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 integrating the OneSignal REST API. 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, or transactional 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), this call must be implemented on your website.

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>

T

We recommend adding the Javascript code inline rather than using a separate file, to avoid compatibility issues.

Fo 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