Integrate OneSignal web push notifications in Matrix

This tutorial takes you through an example of how to integrate Matrix with OneSignal to send push notifications to your customer’s desktop or mobile web application.

Matrix can easily integrate with OneSignal’s web API. You can send custom notifications automatically from OneSignal using native mobile push, web push, email, and in-app messages, based on events triggered within Matrix.

Prerequisites

  • A Matrix site on which to configure OneSignal push notifications. Your Matrix site must be:

    • secured with SSL.

    • accessible from the root level of your domain. For example, www.example.com and not a path within this domain, such as www.example.com/my-site.

    You can configure the URL for your site through your site asset URLs screen.
  • Your Matrix account type must be System Administrator and stored in the System management  System Administrators user group.

Configure OneSignal for Matrix

This section of the tutorial guides you through the process of how to configure OneSignal for Matrix.

Set up a OneSignal account

If you haven’t already created a OneSignal account, visit the OneSignal web site and click Sign Up to begin this process.

For this tutorial, you can use the Free tier described on the OneSignal pricing page.

Add your Matrix site as an app to OneSignal

  1. Sign in to OneSignal.

  2. On the All Applications page, click ADD APP.

  3. In the Add a New App dialog box, specify a meaningful name (for example, the name of your Matrix site) and click ADD APP on the dialog box.

  4. On the Edit App dialog box, click Web Push (for Select Platform).

  5. On the Configure Web Push page, select Typical Site.

  6. In the Site Setup section, specify the following for these fields:

    SITE NAME

    The name of your Matrix site.

    SITE URL

    The URL of your Matrix site.

  7. In the Permission Prompt Setup section, click ADD A PROMPT, and in the Permission Prompt Editor dialog box, choose a PROMPT TYPE and click SAVE.

  8. (Optional) In the Welcome Notification section further down, specify a TITLE and MESSAGE for your initial welcome message.

  9. (Optional) There are several other options you may wish to configure on the Configure Web Push page. Read more about these options in OneSignal’s documentation.

  10. Click SAVE at the end of the page and keep open the resulting Configure Web Push page (with either Upload Files or Add Code to Site at the top).

If prompted, download the OneSignal Web SDK HTTPS Integration Files (from the Upload Files section). OneSignal automatically requests this download if your Matrix site uses SSL and is accessible through HTTPS.

Configure your Matrix site for OneSignal

  1. Ensure you are logged in to your Matrix site in admin mode and have admin permissions to your site.

  2. If your Matrix site is to use HTTPS (and OneSignal prompted you to download its OneSignal Web SDK HTTPS Integration Files as a package), then:

    1. Extract these files, which should be:

      • manifest.json

      • OneSignalSDKUpdaterWorker.js

      • OneSignalSDKWorker.js

    2. Upload each of these files to the root level of your Matrix site. You can do this by adding each file as a new file asset from the root node of your Matrix site (each with a Hidden link link type).

    3. For each of these new file assets, access its details screen and set its Allow Unrestricted Access setting to Yes.

  3. Edit the contents of your Matrix site’s <head> asset, typically stored within the Configuration  Design Assets  Design Nesters folder of your site’s asset tree.

  4. Copy the "Add Code to Site" content from OneSignal’s Configure Web Push page and paste this content into an appropriate area of your Matrix site’s <head> asset. The content of this snippet should look similar to:

    <link rel="manifest" href="/manifest.json" />
    <script src="https://cdn.onesignal.com/sdks/OneSignalSDK.js" async=""></script>
    <script>
      var OneSignal = window.OneSignal || [];
      OneSignal.push(function() {
        OneSignal.init({
          appId: "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
        });
      });
    </script>
    If your Matrix site is not configured to use HTTPS, the <link …​ /> element containing manifest.json is no present in the OneSignal code snippet.
  5. If your Matrix site is configured to use HTTPS, modify the href="/manifest.json" attribute value to use the asset ID value for the manifest.json file you uploaded to your Matrix site. When modifying this value, format it like href="./?a=12345", where 12345 is the asset ID value.

    Find the asset ID value on the asset’s details screen.
  6. Click Save to save changes to the <head> asset.

  7. Visit your Matrix site’s home page (refreshing it if necessary)

  8. Follow the browser prompts so you can accept and subscribe to notifications from your Matrix site (originating from OneSignal).

Confirm Matrix and OneSignal are correctly configured

Check users in OneSignal

  1. Ensure you are logged in to OneSignal and have accessed your Matrix site app dashboard.

  2. Click USERS  All Users.

At this point, you should see a list of users who have subscribed to your notifications (just yourself from your Matrix site so far).

Send a test push notification from OneSignal

Test that push notifications from OneSignal work.

  1. From the Matrix site app dashboard in OneSignal, click MESSAGES and then NEW PUSH on the Messages page.

  2. On the New Message page, set the Audience to "Send to Subscribed Users".

  3. In the Message section, enter a custom TITLE and MESSAGE for your test push notification.

  4. Click CONFIRM at the end of the page.

  5. Click SEND MESSAGE on the Confirm Before Sending message box.

View the message from your Matrix site’s home page.

Set up a push notification from an event-based trigger in Matrix

Create an event-based trigger in Matrix that uses OneSignal’s web API to send REST calls, which triggers a web push notification to any (or a segmented group) of subscribers.

In this example, all OneSignal notification subscribers receive a notification every time a page goes live on your Matrix site.

For this part of the tutorial:

  • Your Matrix account type must be System Administrator and your user account located within the System management  System Administrators user group.

  • Your Matrix site needs to be secured with SSL.

Obtain your OneSignal web API keys

  1. Ensure you are logged in to OneSignal and have accessed your Matrix site app dashboard.

  2. Click SETTINGS  Keys & IDs.

  3. Copy the ONESIGNAL APP ID and REST API KEY values and save them so that they can be copied and pasted later.

Create an event-based trigger in Matrix

  1. Sign in to your Matrix site in admin mode as a user with the system administrator account type.

  2. Add a new trigger asset through System management  Trigger Manager.

  3. On the Create a new Trigger page, specify a Name value of "When a page goes live, send a push notification through OneSignal".

  4. In the Events section, select the "After Status Changed" checkbox.

  5. In the Conditions section, add the following conditions and click Save:

    • Asset Status

    • asset is of type

    • Tree Location

  6. Choose the following values for these conditions:

    Asset Status

    Asset has the current status of "Live".

    Asset is of type

    Match any one of these types: Page (select the Inherit check box)

    Tree Location

    (select the site or part of the site where you want pages going live to trigger the notification).

  7. In the Actions section, choose Call REST resource and click Save at the lower right.

  8. In the Call REST resource section, set the following field values:

    Ignore Permissions

    Select this checkbox.

    METHOD

    Choose POST.

    URL(S)

    Specify https://onesignal.com/api/v1/notifications.

    AUTHENTICATION TYPE

    Set this to "None".

    REQUEST HEADERS

    Specify the following in different fields, ensuring you replace the <REST-API-KEY> with the REST API KEY value you saved above:

    • Content-Type: application/json; charset=utf-8

    • Authorization: Basic <REST-API-KEY>

    REQUEST BODY

    Specify the following in this text field, ensuring you replace the <ONESIGNAL-APP-ID> with the ONESIGNAL APP ID value you saved above:

    {
      "app_id": "<ONESIGNAL-APP-ID>",
      "included_segments": "Active Users",
      "contents": {"en": "%asset_url%"},
      "headings": {"en": "New Page %asset_name% went live."},
      "web_url": "%asset_url%"
    }
  9. Change the status of the trigger to Enabled, which makes the trigger live.

Read more about how to configure additional elements of the request body in OneSignal’s REST API documentation.

Test your event-based trigger

  1. Ensure you are logged in to your Matrix site in admin mode and have admin permissions to your site.

  2. Access the details screen of a page which is currently not live and set its status to Live.

OneSignal detects this change on your site, and you receive a browser notification indicating that the new page went live.

© 2015-2020 Squiz Pty Ltd