OneSignal - Web Push

You can now deliver browser web push notifications in supported browsers (such as Chrome) using Blueshift's Cloud App capability along with a web push SDK provider such as OneSignal. Web push notifications can be orchestrated in campaign journeys and can leverage predictive content recommendations as well as other personalizations. Web push engagement data such as impressions and clicks can be captured via callback urls in Blueshift journeys.

In order to use this capability, you must sign up for browser web notifications at OneSignal.com and use the relevant credentials with your Cloud App template within Blueshift.

Prerequisites

Before you can set up integration with Blueshift, you must have your OneSignal account set up.

Complete the following settings in OneSignal before you set up integration with Blueshift:

Setup a web push app in OneSignal

Before you can integrate with Blueshift, you must have your OneSignal account set up. Follow the steps outlined in this OneSignal document to setup a Web Push app in OneSignal.

To integrate with Blueshift, you need the API Key and the APP ID.

  1. To find the Rest API key, sign in to your OneSignal account and click on your site or app under All Applications on the home page.

    all_application_onesignal.png

  2. After you enter your application/site's page, click on your profile picture in the upper right corner > Account & API keys

    api_keys_settings.png

  3. Copy the API key from the REST API Keys section of the Account Management page that appears.

    onesignal_rest_api_key.png

You must also specify the APP ID in the message template that you use to send the messages to OneSIgnal.

  1. To get the app ID, sign in to your OneSignal account, click on the app or site that you have added to your OneSignal account.

    all_application_onesignal.png

  2. The application/site's dashboard opens. Copy the application ID from the URL bar of the dashboard page.

    onesignal_app_id.png

Add the OneSignal Javascript code to your website

Note

OneSignal will be moving over to a new user-centric data model which supports both user and device identifiers. If you are migrating to their user-centric data model or are setting up a new integration use this Javascript snippet. If you are still on their legacy device-centric data model use the older version. OneSignal will be moving completely to a user-centric data model in future. Refer to these steps to plan your data model migration. 

 

Javascript code for OneSignal's user-centric data model 

Capture OneSignal identifiers on Blueshift Customer profiles using the following JS Snippet in your website.

This script would fire an identify event with onesignal_subscription_id set to the OneSignal subscription id and the onesignal_id set to the OneSignal ID - one of these would be needed for sending out the Web Push message via OneSignal. If you are using any other user-level identifier in OneSignal(for eg. external_id), please update the snippet to capture that identifier as well. 

This snippet is compatible with OneSignal's web push SDK version v16 and above

<html>

   <body>

     <!-- Web Push notification test with Blueshift + OneSignal. 
       This records the OneSignal subscription ID (or player ID) and the Onesignal ID 
       and sends it to  us. -->

     <script>

         OneSignalDeferred.push(function() {
           setTimeout(function() {

             // Uncomment these for debugging purposes

             // console.log("OneSignal Push subscription id: " + OneSignal.User.PushSubscription.id);
             // console.log("OneSignal id: " + OneSignal.User.onesignalId);

             // Send the identify event to Blueshift

             blueshift.identify({
               email: "<<User Email>>",
               onesignal_webpush_id: OneSignal.User.PushSubscription.id,
               onesignal_subscription_id: OneSignal.User.PushSubscription.id,
               onesignal_id: OneSignal.User.onesignalId
             });

            }, 1000);

         });

      </script>

   </body>

</html>

 

Javascript code for OneSignal's device-centric data model (OneSignal legacy data model)

Save the user’s OneSignal user ID (also called player id) on a Blueshift user profile with an identify event.

This would fire an identify event with onesignal_webpush_id set to the OneSignal user identifier that would be needed for sending out the Web Push message via OneSignal.

This snippet is compatible with OneSignal device-centric data model and web push SDK version below v16

<html>

<body>
<!-- Web Push notification test with Blueshift + OneSignal. This records the OneSignal user ID (or player ID) and sends it to us. -->
<script>
OneSignal.push(function() {
   OneSignal.getUserId(function(userId) {
    console.log("OneSignal User ID:", userId);
    blueshift.identify({
      email: "<<User Email>>",
      onesignal_webpush_id: userId
  });
  });
});
</script>
</body>
</html>

Collect engagement data back from OneSignal

After the integration of OneSignal with Blueshift, you can send a notification from the Blueshift platform to the customers of your site through OneSignal.

OneSignal can issue webhook callbacks to a server on message engagement such as impressions or clicks. You can collect these webhook callbacks and send these back to Blueshift as events for segmentation. For more information, see Web Push Webhooks on OneSignal documentation.

In order to use this, you must setup webhook callback urls to your server/app, and once you receive the callback, use the relevant URL in the "data" section to call Blueshift for the engagement tracking. 

Use the webhook URL provided by Blueshift to track a customer impression or click.

Connect the webhook trigger to OneSignal

  1. Sign in to the OneSignal account and click on the app/site that you integrate with Blueshift.
  2. On the dashboard of the application, click Settings. 
  3. Choose All Browsers (except Safari) under Web Push Platforms.
  4. Enable Webhooks in the Webhooks section under Advanced, and provide the webhook URL in the following fields:
  5. Click Save.

Set up integration

To add a OneSignal adapter in Blueshift, complete the following steps:

  1. Sign in to the Blueshift app, and click App Hub in the left navigation menu.
  2. Go to All Apps, search for, and select OneSignal.
  3. You can also go to Web Push Apps and select OneSignal.
  4. Click Configure to view all the configured adapters.
  5. Click +ADAPTER to add an adapter.

    webpush_onesignal.png

  6. Add a Name for the adapter. If you have multiple adapters, the adapter name helps you to identify the integration.
  7. Provide the API Key.
  8. Add information for any Additional Headers.
  9. Click Save to add the adapter.

    The adapter is now added and you can use it in your Cloud App template.

Quick start templates

When you create an adapter in the App Hub, the following quick start template is added to the Cloud App templates.

  • Create notification
  • Create notification (OneSignal ID)

Consider the following points about quick start templates:

  • You can find these in the following location: Templates > Cloud App
  • Quick start templates are identified by the label "QUICK START".
  • A quick start template is added only when you create the first adapter for the app in App Hub. If you have multiple adapters for an app, you can edit the Adapter details on the template Properties tab to select the required adapter.
  • You can use this template as-is in your campaigns. You cannot make any changes to the schema for a quick start template.
  • If you need to change the schema, you can clone the template and then edit the schema as required.

Note

Create Notification(OneSignal ID) quick start template support the schema for OneSignal's new user-centric data model. If you have already migrated to OneSignal's user-centric data model or are setting up a new integration you can use these two quick start templates. If you are still on their Device-centric data model you can use Create Notification template. OneSignal will be moving completely to a  User-centric data model in future. Refer Refer to these steps to plan your data model migration. 

 

Next steps

  1. Configure the OneSignal quick start template to send a payload from a campaign.
  2. You can clone the quick start template and edit the schema if required. You can also create a new template.
  3. Collect engagement data back from OneSignal
  4. Verify integration
  5. In your campaign journey, add a OneSignal trigger. Select the template that you created.

Configure or create a OneSignal cloud app template

A Cloud App template is required to send a payload to OneSignal from a campaign. You can include personalizations and recommendations in the template content. For more information, see Cloud Apps templates.

To use a quick start template or to add a OneSignal Cloud App template, complete the following steps:

  1. Go to Templates > Cloud App.
  2. Complete one of the following actions:
    • Select the Create notification, Create notification(OneSignal ID) or Create notification(Subscription ID) quick start template depending upon your OneSignal data model and use-case.
    • To create a clone of the quick start template, go to the action menu for the template and click Clone.
    • To create a new template, click +TEMPLATES on the Cloud App Templates page. Select the OneSignal app.

      Note: Only apps that support Cloud Apps templates and have atleast one adapter configured are displayed on the Cloud App Templates page.

  3. Go to the Properties tab and configure the template name, add tags and other relevant information.cloudapps_onesignal_properties.png
    Field Description
    Template Name Specify a name for the template to identify it on the index screen. 
    API Endpoint Specify the API endpoint that receives the request that we make. 
    Adapter Select the adapter to use to send the payload.
    Tags

    Specify tags to organize this template.

    Since this template is a Blueshift resource that you use in campaigns, you can use tagging to organize it under folders.

    For more information on this, see Tagging.
  4. Go to the Content tab.

    cloudapps_onesignal_content.png

  5. Go to the Content Form tab and fill the form to specify the data to send to OneSignal.
  6. If you are using a cloned quick start template or a new template, go to the Schema tab and configure the schema for the form.
  7. Provide the APP ID as the value of the app_id key in the source JSON.
  8. For the OneSignal identifiers values in the template, ensure that the value matches the custom user attribute that you add for the customer in the customer profile. For example, if you are using the attribute onesignal_webpush_id ({{user.extended_attributes.onesignal_webpush_id}}), ensure that the custom attribute name that you add to the customer profile is also onesignal_webpush_id. If these two attributes do not match, Blueshift cannot update a customer's webpush ID on the platform.

    onesignal_userprofile_attribute.png

  9. In the preview tab, you can also switch to JSON and view the content in JSON format.

Verify integration

  1. Load your website that integrates with OneSignal’s SDK and requests for the notification permission. You would need to click on the notification icon and grant permissions.

  2. Go to the customer profile in Blueshift. You should see the onesignal_webpush_id in the Custom attributes section if you are using device-centric data model. If you are using user-centric data model you should onesignal_id in the Custom attributes section
  3. Send a Test message using a OneSignal cloud app template. You should see a personalized web push delivered via OneSignal such as:

Migrating to OneSignal's User-centric data model

OneSignal is changing its data model from a Device-centric model(using PlayerID to identify recipient's devices) to a User-centric model (using Aliases to identify users). This data model change allows you to associate multiple devices to a single user. If you are currently using OneSignal's device-centric model and want to migrate to their user-centric model, please follow the following steps

  1. Follow the instructions in OneSignal's migration guide
  2. Once you have updated the OneSignal SDK for your website(step 2 in OneSignal's migration guide) take one of the following steps to update Blueshift integration
    • If you are using Blueshift's Javascript snippet in your website update to the new version of snippet compatible with OneSignal's updated web SDK.

    • If you're not using Blueshift's JavaScript snippet and updating the OneSignal player_id for customer profiles on Blueshift through another method (like API or file upload), please ensure you begin sending the user-level identifiers used in OneSignal (like OneSignal ID or external_id) to Blueshift. For instance, if you're now using OneSignal ID as a user-level identifier, include this new identifier in the data you send to Blueshift.

  3. You may have to do a one time data load for updating all existing customer profiles in Blueshift with the new user-level identifiers from OneSignal. This can be done through customer profile imports
  4. Once the new OneSignal identifiers are available in Blueshift for all customer profiles, update your OneSignal cloud app templates to include the new user-level identifiers under the include_aliases object
    • Blueshift has added Create Notification(OneSignal ID) Quick Start Cloud App template that you can use in your campaign journeys to send web push to OneSignal using OneSignal ID.
    • In case you are using a different user level identifier in OneSignal you can clone this template and add the identifier in the schema to use the templates in your journeys. For example, if you are using external_id as a user level identifier in OneSignal you can add external_id under the include_aliases object, save the cloned template and use it in your campaigns

No update to your OneSignal adapters in Blueshift is needed for this migration

Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.