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.

Before you start

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.

Configuring 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 select 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

Sign in to OneSignal.
On the All Applications page, select ADD APP.
In the Add a New App dialog box, specify a meaningful name (for example, the name of your Matrix site) and select ADD APP on the dialog box.
On the Edit App dialog box, select Web Push (for Select Platform).
On the Configure Web Push page, select Typical Site.
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.
In the Permission Prompt Setup section, select ADD A PROMPT, and in the Permission Prompt Editor dialog box, choose a PROMPT TYPE and click SAVE.
(Optional) In the Welcome Notification section further down, specify a TITLE and MESSAGE for your initial welcome message.
(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.
Select 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

Ensure you are logged in to your Matrix site in admin mode and have admin permissions to your site.
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.
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.
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.
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.
Select Save to save changes to the <head> asset.
Visit your Matrix site’s home page (refreshing it if necessary)
Follow the browser prompts so you can accept and subscribe to notifications from your Matrix site (originating from OneSignal).

Confirming that Matrix and OneSignal are correctly configured

Follow the procedures in this section to verify that Matrix and OneSignal are correctly configured.

Check users in OneSignal

Ensure you are logged in to OneSignal and have accessed your Matrix site app dashboard.
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.

From the Matrix site app dashboard in OneSignal, select MESSAGES and then NEW PUSH on the Messages page.
On the New Message page, set the Audience to "Send to Subscribed Users".
In the Message section, enter a custom TITLE and MESSAGE for your test push notification.
Select CONFIRM at the end of the page.
Select SEND MESSAGE on the Confirm Before Sending message box.

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

Setting 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

Ensure you are logged in to OneSignal and have accessed your Matrix site app dashboard.
Click SETTINGS Keys & IDs.
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

Sign in to your Matrix site in admin mode as a user with the system administrator account type.
Add a new trigger asset through System management Trigger Manager.
On the Create a new Trigger page, specify a Name value of "When a page goes live, send a push notification through OneSignal".
In the Events section, select the "After Status Changed" checkbox.
In the Conditions section, add the following conditions and select Save:
- Asset status
- asset is of type
- Tree location
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.
In the Actions section, choose Call REST resource and select Save at the lower right.
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%"
}
```
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

Ensure you are logged in to your Matrix site in admin mode and have admin permissions to your site.
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.

Help Center

Menu