Third-party Web Migration

This is a general guide for migrating web users to Airship from a different push notification provider.

Migrating your web audience to Airship is a straightforward process and should work for most integrations, as web notification providers generally use the same protocols. This tutorial is meant to be followed by a web developer.

In this tutorial, you will complete the following steps:

  1. Create an Airship account.
  2. Enable your project for web notifications and download the configuration files.
  3. Replace the contents of your existing service worker for your current provider with Airship service worker contents.
  4. Replace the HTML snippets that load the web push SDK with Airship-specific code.
  5. (Optional) Remove manifest.json.
  6. Wait 24 hours.
  7. Update the service worker by pushing one last message from your old provider.
  8. Verify that channels are being created in Airship.

Create an Airship Account

After signing your Airship contract, create an Airship account via one of the following links, depending on your preferred data center:

The person at your company who creates this account should be the primary day-to-day contact with the Airship team. Typically this is your marketing lead, product owner, etc.

After you have created your account, see Manage Messaging Team Invitations to add your web developer to the project. They must have Full Access or Administrator permissions to complete the migration.

Enable your project for Web

Create a project in the Airship dashboard and configure it for web notifications.

After you have completed the above steps, you will download a ZIP file containing the files you will need for the migration:

  • push-worker.js
  • snippet.html

In the next two steps, you will replace the contents of your current web notification integration with the contents of these two files.

 Note

See our Web Getting Started Guide for more details on Airship web notifications.

Substitute Service Worker

Replace the contents of your current service worker with the code in push-worker.js that you downloaded in your Airship bundle.

The service worker should be in the root of your site, and will likely have a name that reflects your current provider, such as pushwoosh-service-worker.js or OneSignalSDKWorker.js.

push-worker.js
// 86acbd31cd7c09cf30acb66d2fbedc91daa48b86:1601486279.1242173
importScripts('https://aswpsdkus.com/notify/v1/ua-sdk.min.js')
uaSetup.worker(self, {
  defaultIcon: 'https://mysite.com/images/icon.png',
  defaultTitle: 'Default Push Icon Title',
  defaultActionURL: 'https://mysite.com',
  appKey: 'dbYFpjwBQrWxThKEO1fOIQ',
  token: 'MPpkYllGU2p3QlFyV25UaEtFTzFmT0lROkliVnRIVk5PTVB1X2hZLXRxc0pNNG8yTkdHV0hhVmpkUkdzaGl0ZF9ROW8',
  vapidPublicKey: 'BL_IS36oShED3ACGuK9nnGt6TF7RN8LvhveRd4YsVohbN3Tndm94ZKJlq-3qASJaa8bCGc3mU5YatYJqg8XOd4E'
})

 Important

Service worker registrations are linked to the location of the worker, including its filename. Do not rename the service worker filename; otherwise users would need to re-register.

Replace HTML snippets

Next, replace the HTML in your site that loads and calls the SDK with the contents of snippet.html.

You must set the value of the workerUrl property to the filename of the push worker that we modified in the previous step, e.g., workerUrl:"/pushwoosh-service-worker.js",.

The example below illustrates a migration from Pushwoosh to Airship.

New configuration in HTML files
<!DOCTYPE html>
<html>
    <head>
        <link rel="manifest" href="/manifest.json">
<!-- REMOVE OLD PUSHWOOSH SCRIPT> -->
<!--<script src="https://cdn.pushwoosh.com/webpush/v3/pushwoosh-web-notifications.js" async></script>-->
    </head>
    <body>
    </body>
</html>
<script>
/*---------------------------------------
SECTION TO REMOVE
---------------------------------------*/
/*var Pushwoosh = Pushwoosh || [];
Pushwoosh.push(
  [
    "init",
    {
      logLevel: 'debug', // possible values: error, info, debug
      applicationCode: '29981-D302F',
      safariWebsitePushID: 'web.com.example.domain',
      defaultNotificationTitle: 'Pushwoosh',
      defaultNotificationImage: 'https://cp.pushwoosh.com/img/logo-medium.png',
      autoSubscribe: true,
      userId: 'user_id',
      tags: {
        'Name': 'John Smith'
      },
      subscribePopup: {
        enable: true,          // (boolean) popup activation
        text: 'Text on popup', // (string) a text to display on the popup
        askLaterButtonText: 'Not now', // (string) custom text for the "Ask later" button
        confirmSubscriptionButtonText: 'Subscribe', // (string) custom text for the "Subscribe" button
        iconUrl: 'https://...',  // (string) custom icon URL
        delay: 60,             // (integer) a delay between the page loading and popup appearance
        retryOffset: 604800,   // (integer) an offset in seconds to display the popup again
        overlay: false,        // (boolean) enables page overlaying when popup is displayed
        position: 'top',       // (string) position on the page. Possible values: 'top' | 'center' | 'bottom'
        bgColor: '#fff',                         // (string) popup's background color
        borderColor: 'transparent',              // (string) popup's border color
        boxShadow: '0 3px 6px rgba(0,0,0,0.16)', // (string) popup's shadow
        textColor: '#000',      // (string) popup's text color
        textSize: 'inherit',    // (string) popup's text size
        fontFamily: 'inherit',  // (string) popup's text font
        subscribeBtnBgColor: '#4285f4',     // (string) "Subscribe" button's color
        subscribeBtnTextColor: '#fff',      // (string) "Subscribe" button text's color
        askLaterBtnBgColor: 'transparent',  // (string) "Ask later" button's color
        askLaterBtnTextColor: '#000',        // (string) "Ask later" button text's color
        theme: 'material' // or 'topbar'. A popup theme, see the details below
      }
    }
  ]
);*/


/*---------------------------------------
END SECTION TO REMOVE
---------------------------------------*/

/*---------------------------------------
NEW AIRSHIP INTEGRATION
---------------------------------------*/
// 86acbd31cd7c09cf30acb66d2fbedc91daa48b86:1582908843.6751363
!function(n,t,c,e,r){var u,i,o=[],a=[],f={then:s,catch:function(n){return s(!1,n)},_async_setup:function(n){var t;try{t=n(r)}catch(n){
return i=n,void h(a,n)}t.then((function(n){h(o,u=n)})).catch((function(n){i=n,h(defferedErrors,i)}))}};n[e]=f
;var d=t.createElement("script");function h(n,t){for(var c=0;c<n.length;c++)p(n[c],t)}function s(n,t){return n&&(u?p(n,u):o.push(n)),
t&&(i?p(t,i):a.push(t)),f}function p(t,c){n.setTimeout((function(){t(c)}),0)}d.src=c,d.async=!0,d.id="_uasdk",d.rel=e,t.head.appendChild(d)
}(window,document,'https://aswpsdkus.com/notify/v1/ua-sdk.min.js',
  'UA', {
    workerUrl:"/pushwoosh-service-worker.js",
    vapidPublicKey: 'BCPktGJSXdwt9Jih-iWpVAjLdNL-9UhFL3-8mQHj7uwXU_KmSLHppFGYTfr2MLvj3v-5qq-RzxSmCzXFOZChivg=',
    appKey: 'oHM-J3NYTkGkL0SxGL36vg',
    debug: true,
    token: 'MTpvSE0tSjNOWVRrR2tMMFN4R0wzNnZnOk1NLVJidTRwN2FyQ2EtOEhpSVlPV3NNMjY3MXpxdVUxbVVSTDBHUG94NEk'
  });
/*---------------------------------------
END NEW AIRSHIP INTEGRATION
--------------------------------------*/
</script>

Remove manifest.json

If your web application uses a manifest.json to store GCM credentials, you can remove the file if it is not needed for anything else. Also remove references to it, i.e., <link rel="manifest" href="/manifest.json">.

Airship uses the VAPID web push protocol and therefore we do not rely on a manifest.json file to store the GCM sender ID.

Wait 24 hours

Next, wait! Make sure that no one in your organization attempts to send notifications, either from your previous provider or Airship, for 24 hours. The 24-hour waiting period is mandatory, owing to the nature of service workers.

Send a broadcast push notification

After 24 hours from the time you complete the SDK integration steps, send a broadcast push notification to your entire audience from your previous provider. This must be a broadcast notification to all users. Any end user that receives the push notification will be moved to Airship without having to visit your website and without having to opt in to notifications again. Devices must be online to receive this notification.

The migration is now complete.

 Note

End users may see a browser notification that says “This site has been updated in the background.” This is the expected behavior when changing the service worker.

Verify the migration

Now that you have updated your site with Airship code, and waited the requisite 24 hours, you can verify that new registrations are working via the Airship SDK.

Here are a few SDK methods that you can use in the developer console to verify the SDK is working properly:

// Register a channel
UA.then(sdk => console.log(sdk.register()))

// Check if the channel is opted in
UA.then(sdk => console.log(sdk.channel.optedIn))

// Opt out. You must re-register after
UA.then(sdk => console.log(sdk.channel.optOut()))

// Get channel ID
UA.then(sdk => console.log(sdk.channel.id))

// Add tag
UA.then(sdk => console.log(sdk.channel.tags.add("avocado")))

// List tags
UA.then(sdk => console.log(sdk.channel.tags.list))

// Check for existence of a tag
UA.then(sdk => console.log(sdk.channel.tags.has("avocado")))

// Set named user
UA.then(sdk => console.log(sdk.channel.namedUser.set("pierre")))

// List named user
UA.then(sdk => console.log(sdk.channel.namedUser.id))

You can also check to see that data is going into Airship by checking browser storage:

Finally, you can verify users are being created by using the Contact Lookup in the Airship dashboard.