Accengage Upgrade

Upgrade your Accengage notification users to Airship.

 Note

Ce contenu est également disponible en français.

If you are reading this document, you are ready to move your Accengage audience to the Airship service. And we are ready to help you accomplish this goal.

Much of this process is automated by Airship, but you will need to perform certain actions on your end, such as creating an Airship account, configuring your project in our dashboard, and implementing the Airship SDK. This guide will take you through those steps.

Create an Airship Account

After signing your Airship contract, create an Airship account via this signup link.

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.

Team Access

Your account owner may grant access to others in Settings » Team Access. Follow the steps in Manage Messaging Team Invitations.

 Important

Your developer must have access to your project, with Full Access or Administrator permission. This is required to complete the implementation steps.

Project (Environment) Setup

 Important

In Accengage you have a unique environment for each messaging channel. In Airship, rather than an environment for each channel, you will have a project to which you may add multiple channels, e.g., app, web, SMS, etc.

Typically you will have at least two projects for each branded website and/or mobile app: one project for each Live (production) and Test (development) environment, and additional projects for other test or staging environments.

Airship will create your projects for you. If you are moving your app and/or web notification service from Accengage to Airship:

  • Web — Airship will configure the Web channel with your web push details, including your default URL and default image.

     Important

    Web upgrades for Safari are not supported. Due to how Safari web push works, you must use a new website push ID, not the one used in Accengage. This means Airship will not configure Safari support for you, you must add it to your Web channel configuration yourself.

    • Requirements and steps for adding Safari support are included in the web channel documentation referenced in the Integrate the Airship Web SDK sections on this page. We recommend setting up Safari when you first integrate the Airship Web SDK; if you add Safari support at a later date, you must update your website with the new configuration files. (Whenever you make any edits to your web channel configuration, you must update your website with the new configuration files.)

    • You can message your existing Safari users through Accengage, but in Airship you will build a new audience by users revisiting the website and opting in again (after you configure Safari in Airship and complete setup for Web).

  • iOS and Android — You must configure your iOS and Android channels. Steps to do so are provided in the App Setup section.

Your account owner or a team member with Full Access or Administrator permission must go to Settings » Edit Project and review the Industry and Sub-industry set for your project, and make new selections if they are set incorrectly. See our Industry Types for examples.

We recommend reading our Platform Overview content, starting with What Is Airship?, before you continue.

App Setup

Your account owner or a team member with Full Access or Administrator permissions must complete the following actions:

  1. Go to Settings » Quickstart Guide.

  2. Click Add Channel   and select the app channels (iOS and/or Android) you want your project to support. Click outside the selection box to close it.

  3. Click a channel and follow the setup steps.

  4. Set up push provider:

    In this step you will configure the push notification provider for your app: APNs for iOS, FCM for Android. Follow the instructions below for your target platform and then proceed to Step 5 to install the transitional SDK.

    iOS

    We recommend using token signing for authentication for your app in Airship. Complete the steps in the following two sections of our iOS documentation in order to register your authentication signing key and configure token-based authentication in Airship:

    • Apple Setup
    • Airship Steps
       Important

      If you choose to use certificate authentication instead, you must generate a new APNs push certificate for your app in Airship. Do not reuse the same certificate used in the Accengage platform.

      Complete the steps in the following two sections of our iOS documentation in order to create, export, and upload your Apple push certificate:

    Android

    You must reuse the same FCM project and package name in Airship as in Accengage. We also recommend using your existing server key.

  5. Install the Airship SDK.

    We provide modules in both our iOS and Android SDK to assist you while transitioning from the Accengage service to the Airship service.

  6. Send a test push notification to your app:

  7. Update calls to the Airship SDK that are a part of your integration.

    Now that you have installed our mobile SDK and configured notifications, the following features will either map automatically or with minimal effort:

    • Device ID: Device IDs will retain the same values but will be mapped to Channel IDs in Airship.

    • Attributes: All attributes that exist at the user level in Accengage will migrate to Airship, but you must define the attributes in the Airship UI. See Add Attributes to Your Project to learn how.

    • Customer IDs can be mapped to Named Users.

    The following features are available in the Airship SDK but are not mapped directly to the Accengage SDK.

 Note

Your deep links may already work with the Airship SDK. If they don’t, our Deep Link documentation explains how to set up a deep link listener. See links to the iOS and Android deep link documentation in step 7 above.

Post-Implementation

After you set up your App with Airship:

  1. Continue to use the Accengage UI to send notifications to your full audience for ~30 days. You will be able to use the Accengage UI to send notifications to non-upgraded users, upgraded users, and new users who have registered via the Airship SDK since you implemented it. If you use Accengage’s In-App messaging feature, we recommend creating an in-app message encouraging users to update their app.

  2. After ~30 days, or when most or all of your active audience has updated their app, start using the Airship UI exclusively for all app messaging.

 Note

It is not possible to guarantee that every user will move from Accengage to Airship during this process, due to inactive users, outdated registrations due to new devices, users' devices being offline for extended period of time, etc.

During this 30-day period, reporting is affected by where you send a message from (Accengage, or Airship) and if the user has updated their app:

  • If you send using Accengage, the message goes to all users.
    • For non-upgraded users (they have not yet updated their app and are still on Accengage), full reporting is available in Accengage.
    • For upgraded users (they have updated their app and are now on Airship), send count is in Accengage, open counts are in Airship.
    • For net new users (they downloaded your app for the first time after you upgraded it to the Airship SDK), send count is in Accengage, open counts are in Airship.
  • If you send using Airship, the message is sent to users who have upgraded (they have updated their app and are now on Airship) and to net new users, and full reporting is available in Airship.

Web Setup

Your account owner or a team member with Full Access or Administrator permission must confirm your default URL and default image in Settings » Channels » Web Notifications and update any value that is incorrect or outdated. These fields were brought over from the Accengage system as part of the upgrade process.

Before beginning the implementation process, we recommend sending a broadcast notification to your entire audience via the Accengage UI. The goal of this step is to ensure your messaging audience is up to date, because in some cases we do not receive opt-out feedback about a user until attempting to send a notification to them. If you regularly send broadcast notifications to your audience already, you can skip this step.

The steps in the Implementation sections should be handled by your web developer. Your web developer must have an Airship account with Full Access or Administrator permission for your project. See Team Access above.

Implementation — Your Own Domain

Follow these steps if you enabled the setting Use my own domain in the Accengage platform. If not, use the implementation steps for Accengage Domains.

Initiate Upgrade

  1. In the root of your site, remove the acc_ww.js file, leaving everything else as is. Do not remove the Accengage Service Worker (acc_sw.js).

  2. Remove the Accengage JavaScript snippet from every page on your website.

    Accengage JavaScript snippet
        <script>
        (function(l,o,a,d,i,n,g,w,e,b){
        g='AccengageWebSDKObject';w='script';l[g]=l[g]||{};l[g][n]=d;
        l[d]=l[d]||[];l[d].p={'date':1*new Date(),'window':l,'document':o,'params':a};
        e=o.createElement(w);b=o.getElementsByTagName(w)[0];e.async=1;
        e.src='https://'+n+i+'/init.js';b.parentNode.insertBefore(e,b);
        })(window,document,{},'ACC','/pushweb/assets','customer-by.accengage.net');
        </script>
        

    Note: In older Accengage integrations, we relied on a manifest.json file to store the GCM sender ID. This file is no longer required since we now use the VAPID web push protocol.

    You may safely remove the line <link rel="manifest" href="/manifest.json"> and the manifest.json file if you do not require them for anything else.

  3. Log in to the Airship UI, go.airship.eu.

  4. Go to Settings » Channels » Web Notifications » Accengage Upgrade.

  5. Click Start Upgrade and click Yes.

After clicking Yes, you will see a message that says “Do not cancel upgrade unless you’re instructed to by Airship.” You are now ready to integrate the Airship web SDK into your website.

Integrate the Airship Web SDK

  1. Configure your web channel, and add Safari support, if needed; see note for Web in Project (Environment) Setup above. In the last step, you will download your SDK bundle.

  2. Replace the content of the file acc_sw.js from Accengage with the content of the file push-worker.js from Airship.

  3. Specify the setting workerUrl: "/acc_sw.js" in your on-page Airship snippet and in your secure-bridge.html if you’re using one.

  4. Implement the Airship SDK by following the steps in Web: Getting Started.

Implementation — Accengage Domains

Follow these steps if you used an Accengage (now Airship) hosted domain to register (opt in) web users. If not, use the implementation steps for Your Own Domain.

Initiate Upgrade

  1. Remove the Accengage JavaScript snippet from every page on your website.

    Accengage JavaScript snippet
        <script>
        (function(l,o,a,d,i,n,g,w,e,b){
        g='AccengageWebSDKObject';w='script';l[g]=l[g]||{};l[g][n]=d;
        l[d]=l[d]||[];l[d].p={'date':1*new Date(),'window':l,'document':o,'params':a};
        e=o.createElement(w);b=o.getElementsByTagName(w)[0];e.async=1;
        e.src='https://'+n+i+'/init.js';b.parentNode.insertBefore(e,b);
        })(window,document,{},'ACC','/pushweb/assets','customer-by.accengage.net');
        </script>
        
  2. Log in to the Airship UI, go.airship.eu.

  3. Go to Settings » Channels » Web Notifications » Accengage Upgrade.

  4. Click Start Upgrade and click Yes.

After clicking Yes, you will see a message that says “Do not cancel upgrade unless you’re instructed to by Airship.” You are now ready to integrate the Airship web SDK into your website.

Integrate the Airship Web SDK

Please read Secure Bridge/Multiple Non-Registration Domains below before starting implementing the Airship Web SDK.

  1. Configure your web channel, and add Safari support, if needed; see note for Web in Project (Environment) Setup above. In the last step, you will download your SDK bundle.

  2. If you need to combine the push worker with an existing service worker, you may need to specify a new location for your worker file. You can do this by adding a workerUrl: "/acc_sw.js" setting to your on-page snippet, inside your service worker, and to your secure-bridge.html if you’re using one.

  3. Implement the Airship SDK by following the steps in Web: Getting Started.

Secure Bridge/Multiple Non-Registration Domains

If you used an Accengage (now Airship) hosted domain to register (opt in) web users and you also want to use the Airship SDK on your own website (to prompt users to opt in before directing them to the registration domain), refer to this information when following the steps in Web: Getting Started. If you use your own HTTPS domain to register (opt in) web users, you can skip this Secure Bridge section.

 Note

In Airship, the Master domain is known as the Registration domain and your registered domains are your allowed domains.

  1. When configuring your web channel in Settings » Channels » Web Notifications, enable Secure Bridge. By default, the secure bridge only communicates with the non-HTTPS version of the registration domain. If you need to use the secure bridge with other domains, enter those domains in the Allowed Domains box.

    When you select the Secure Bridge option, your SDK bundle will include a secure-bridge.html file. This file must be placed on your registration domain.

  2. Place the JavaScript snippet (contained in the snippet.html file) on every allowed domain on which you want to show the soft opt-in prompt to your website visitors.

  3. Ensure that the registrationDomain and secureBridgePath are specified on all allowed domains you wish to prompt users on. The registrationDomain property must be a domain name accessible through HTTPS, but it must be specified in the config without the https prefix. Examples:

            “airship.com”, “www.mydomain.com”, “mysubdomain.domain.com”
            

    When specifying a registration domain, calling sdk.register() will fail if not executed on this specified registration domain. The promise returned will be rejected with message “Domain is not allowed for registration.”

Multiple Registration Domains

Some Accengage customers use an Accengage-hosted domain in order to register users in non-secure contexts. For example, Acme Corp may have a site at acme-corp.com but use acme-corp-by.accengage.net to register web notification users.

In order to migrate to Airship in this scenario, we want to make sure that the following outcomes are achieved:

  1. For new registrations, you will use your own domain, using the Secure Integration method if necessary.
  2. Existing registered users will be recognized on both HTTP and HTTPS with the configuration settings provided below. This way, whether a user had previously registered on your-site.com or your-company-by.accengage.net, they will still receive notifications.
 Note

If you want to prompt users on various websites, use the secure bridge in combination with registrationDomain and allowedDomains.

If you use or have ever used the Accengage-hosted domain to register users, you must set up the secure bridge, with the secureBridgeUrl set to https://YOUR-COMPANY-by.accengage.net/pushweb/assets/secure-bridge.html. Replace YOUR-COMPANY with the master domain that Accengage dedicated to you.

You may combine the use of the registrationDomain/allowedDomains properties with the use of secureBridgeUrl if necessary.

Once these steps are taken, a user will only ever be registered on one of the two domains. This will prevent users from receiving notifications twice.

Setup

Configure the Airship Web SDK with the following values:

  1. Set mixedRegistrationDomains to true.

  2. Set registrationDomain to your site’s URL, e.g., your-domain.com.

  3. allowedDomains should include both HTTP and HTTPS versions of your site, to allow for registrations that originate from non-secure pages.

  4. If you were using a “your-company-hosted-by.accengage.net” domain for registrations, you must set a config value for the secureBridgeUrl property, e.g., https://YOUR-COMPANY-by.accengage.net/secure-bridge.html.

  5. Upload push-worker.js to the customer.com domain. No special configuration is necessary.

 Note

There are two methods to setting the final value of the secure bridge URL.

  • secureBridgeUrl — Set the fully-qualified URL. Example: your-domain.com/path/to/secure-bridge.html
  • secureBridgePath — Set the path to the HTML file, and Airship will concatenate with registrationDomain to create the final URL. Example: /path/to/secure-bridge.html

Example config for multiple domains:
var config = {
    workerUrl: "/push-worker.js",
    registrationDomain: "your-domain.com",
    mixedRegistrationDomains: true,
    secureBridgeUrl: 'https://your-domain.com/path/to/secure-bridge.html',
    allowedDomains: [
        'http://your-domain.com'
        'https://your-domain.com'
    ]
};

Any configuration required on the Accengage registration domain will be handled by Airship staff.

Post-Implementation

 Important

We updated our upgrade process due to a change to Chromium-based browsers that impacted Airship’s ability to move users from Accengage to Airship via a web notification; we updated the Accengage service worker to make it possible for users who visit your site prior to beginning your Airship implementation (and therefore have the updated Accengage service worker) to continue to be migrated to Airship via a web notification.

The majority of your website visitors will move to Airship by visiting your website after you’ve gone through the implementation steps above. During the upgrade process, you should send notifications to your audience from the Accengage dashboard to try to drive them to your website. Upon visiting, their service worker will be updated to the Airship service worker, and they will be registered for web notifications in the Airship platform.

A subset of your users — those who visited your site regularly prior to the upgrade process — can be moved without visiting your site again, by receiving a web notification. To move these users, please follow the steps below after your web developer has completed the SDK integration:

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

  2. After 24 hours from the time when your web developer completed the SDK integration steps, send a broadcast notification to your entire audience from the Accengage UI. This must be a broadcast notification to all users. End users who regularly visit your website may 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.

  3. Continue to use the Accengage UI to send notifications to your full audience for ~30 days. You will be able to use the Accengage UI to send notifications to non-upgraded users, upgraded users, and any new users who have registered via the Airship SDK since you implemented it.

  4. After 30 days, or when approximately 80% of your audience has moved to Airship (whichever comes first), start using the Airship UI exclusively for all web notifications.

 Note

It is not possible to guarantee that every user will move from Accengage to Airship during this process, due to inactive users, outdated registrations due to new devices, users' devices being offline for extended periods of time, etc.

User Mapping

After a user is moved from Accengage to Airship, they will retain the same unique identifier (UUID) in the Airship database. In Accengage, this ID was known as a Device ID. In Airship, it is known as a Channel ID.

If you previously mapped your Accengage Device IDs to a customer number or other internal identifier using the Accengage client ID field, you can reestablish the mapping to Channel IDs using Named UsersA customer-provided identifier used for mapping multiple devices and channels to a specific individual. .

Named User Migration Example

In this example we will take a CSV file containing your Accengage user data and map the Accengage Customer IDs to Airship Named Users.

 Note

If using this example script, make sure that you match the device_type in the associate call to the platform of the users you are migrating to Airship. For example, to migrate your iOS users, you would use named_user.associate(device_id, 'ios').

  1. Begin by downloading your user data from the Accengage UI. Then go to Targeting » Export targets.

  2. Click Export Database in CSV to save the file.

  3. Use the Named User Association endpoint to map Accengage Device and Customer IDs to Airship Channel IDs and Named Users.

    The example below uses the Airship Python Library to iterate over the CSV file and map Customer IDs to Named Users.

    You may also wish to try one of our other API wrappers to accomplish the same goal.

    import csv
    import urbanairship as ua

    app_key="<YOUR_APP_KEY>"
    master_secret="<YOUR_MASTER_SECRET>"

    # Create the Airship object

    airship = ua.Airship(app_key, master_secret)

    with open('export_xxx.csv') as migration_file:
        next(migration_file)
        accengage = csv.reader(migration_file, delimiter=';')
        for row in accengage:

            # Retrieve the "Device ID" (first column).
            device_id = row[0]

            # In this example Customer ID is the last column of our CSV.
            # Use the correct index for your setup.
            customer_id = row[-1]

            # Create a named user that maps to your Customer ID.
            named_user = ua.NamedUser(airship, customer_id)

            # Associate the named user with your Channel ID (formerly device ID).
            r = named_user.associate(device_id, 'web')

            # Print the results to the console.
            print(r, "Channel ID: ", device_id, "Named User: ", customer_id)