Accengage Upgrade

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 » Project Configuration » Team Access. Follow the steps in Manage Messaging Team Invitations.

Project (Environment) Setup

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 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. Configure the app channels (iOS and/or Android) you want your project to support.

   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.

    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 our iOS documentation in order to create, export, and upload your Apple push certificate: Certificate auth.

   Android

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

   • FCM Setup

2. 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.

   • iOS SDK Migration
   • Android SDK Migration

3. Send a test push notification to your app.

   See Send Your First Message or our API reference.

4. 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 Adding 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.

   • Custom Events: Mobile Custom Events
   • Deep Links: Mobile Deep Linking
   • Tags: Mobile Device Tags

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.

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 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 » 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 » 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.

1. When configuring your web channel in Settings » Channels » Web, 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.

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.

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

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.

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.

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)