Configure Channels

iOS channel configuration

To configure an iOS channels, you must configure Apple Push Notification Service (APNs). To do this, you can either use token or certificate auth. It is recommended to use token auth to simplify setup and to avoid having to renew your certificate every year.

Consider the following as they relate to authentication setup and app development:

• Default and fallback behavior — Airship defaults to token-based authentication for APNs but will fall back on certificates if token authentication is not configured. For existing projects, it is recommended that you leave your certificate in place when migrating to token-based authentication so that push can be quickly restored if there are any issues during that process. Also, if you remove your certificate before setting up token-based authentication, you may have a period when you cannot send messages.

  After confirming token-based authentication is working, you can let the certificate expire, or revoke the certificate from the Apple Developer Member Center.

• Production vs. Development Projects — When you create or edit an Airship project (and thus its application record on our server), you must select whether your app system is Test (development for sending test messages) or Live (production for sending messages to customers).

  Apple treats the production and development servers separately, so a device token for a test sandbox will not work on a production sandbox. Because of this, we suggest creating both Live and Test projects in the Airship dashboard so you can continue to build and develop your application without interrupting your users. Configure the development credentials for the test project, and production credentials for live project. Then switch between the two credentials using the inProduction flag when configuring the Airship SDK.

   Warning

  Do not a) submit to the App Store or b) test notifications on an ad hoc build while your app’s code is pointing to an Airship app key that is set as Test. Test apps use different tokens that, when included in a push to a Live app, will fail and in many cases cause all other pushes to fail.

  Always create a Live Airship project first, and make sure your application code is pointing to the live project’s app key. For more tips on what to check before you release your app, see the iOS Production Launch Checklist ).

Token auth (Recommended)

First, get your identifiers for your iOS app ID and register and download a new key. You will use them when configuring the iOS channel in Airship.

1. Log in to the Apple Developer Member Center .

2. Go to Account, then Membership details, then note your Team ID.

3. Go to Program Resources, then Certificates, IDs & Profiles, then Identifiers.

4. If you already registered an iOS App ID:

   1. Select its name in the list of App IDs.
   2. Note the Bundle ID for the app.
   3. Enable Push Notifications.

      

   4. If Push Notifications was already enabled, select All Identifiers at the top of the page to go back. Otherwise, select Save.
   5. Go to step 6 below.

5. If you have not already registered an iOS App ID, add one now:

   1. Select the plus icon (), then select App IDs.

      

   2. Select Continue.
   3. Fill out the Register an App ID form and enable Push Notifications. Also note the Bundle ID you enter.

      

   4. Select Continue, then Register.
   5. Continue to step 6 below.

6. Register a new key:

   1. In the sidebar, select Keys.
   2. Select the plus icon ().
   3. Enter a unique key name.
   4. Enable Apple Push Notifications service (APNs).

      

   5. Select Continue, then Register.

7. Note the Key ID, then select Download to save the key in .p8 format.

   

    Important

   Be sure to save your key in a secure location if you intend to use it across multiple apps or Airship projects. Apple only allows two registered APNs keys per team, so reaching this limit would require you to revoke one of your existing keys before creating a new one, which in turn would require an update for any apps previously using the revoked key. Airship will not make your key available for download or sharing across projects once it has been uploaded.

Now you can configure the iOS channel for the project in Airship:

1. Go to Settings.
2. Under Channels, select Mobile Apps, then iOS.
3. For Token-based authentication, select Edit.
4. Under Signing key, upload your .p8 file.
5. Enter your Team, Bundle, and Key IDs.
6. Select Save.

Certificate auth

1. Log in to the Apple Developer Member Center .

2. Go to Account, then Program Resources, then Certificates, IDs & Profiles, then Identifiers.

3. If you already registered an iOS App ID, select its name in the list of App IDs, then go to step 5 below.

4. If you have not already registered an iOS App ID, add one now:

   1. Select the plus icon (), then select App IDs.

      

   2. Select Continue.
   3. Fill out the Register an App ID form and enable Push Notifications.

      

   4. Select Continue, then Register.
   5. Select your app’s name in the list of App IDs, then continue to step 5 below.

5. Under Capabilities, enable Push Notifications, then select Configure. The button is labeled Edit if it was previously configured.

   

    Note

   If the Configure/Edit button is not available, you may not be the team agent or an admin. The person who originally created the developer account is your team agent, and they will have to carry out the remaining steps in this section.

6. Select Create Certificate:

   

   You should now see the Create a New Certificate section, where you will generate an Apple Push Notification service SSL (Sandbox & Production) certificate compatible with both the Production and Development environments:

   

7. Follow Apple’s instructions to create a certificate signing request , then upload the file under Create a New Certificate.

8. Select Continue after uploading your certificate signing request.

   You can now use the newly-created Certificate Signing request to generate the APNs Push SSL certificate. The next step requires the Download button to be active. You may need to reload the page if it is not yet active.

9. Select Download and save the file for use in the next step.

   

10. Open the certificate you downloaded in the previous step. It should open in the Keychain Access app and be listed in My Certificates.

    

11. Select the certificate in the list, then from the File menu, select Export Items….

    

     Note

    Be sure to select My Certificates under the Category menu on the lower left-hand side. If My Certificates is not highlighted, you will not be able to export the certificate as a .p12 file.

12. Save the file in the Personal Information Exchange (.p12) format.

    

    You will be prompted to create a certificate password. Use this password in the Airship dashboard.

Now you can configure the iOS channel for the project in Airship:

1. Go to Settings.
2. Under Channels, select Mobile Apps, then iOS.
3. For Certificate-based authentication, select Edit.
4. Enter the certificate password and upload the .p12 file.
5. Select Save.

Android channel configuration

To configure Android channels, you must configure either Firebase Cloud Messaging (FCM) and/or Huawei Mobile Services (HMS). If both push providers are configured, the Airship SDK prioritizes FCM as the push provider if the app and the SDK are set up for both.

FCM authentication methods

There are two authentication methods for FCM:

• Server key authentication is for Firebase projects using Google’s legacy Cloud Messaging API, which uses HTTP and XMPP protocols for sending and receiving messages.

• Token-based authentication is for Firebase projects using Google’s FCM HTTP v1 API, which uses short-lived access tokens that follow the OAuth2  security model. These tokens provide better security than server key since, in the event of tokens becoming public, they can only be used for about an hour before they expire.

FCM token auth (recommended)

First, enable the Firebase Cloud Messaging API (V1) for your Firebase project:

1. Log in to the Firebase console .
2. Either create a new project or select an existing project that you want to configure with Airship.
3. In the sidebar, select the gear icon (), then Project settings:

   

4. Select the Cloud Messaging tab.
5. For Firebase Cloud Messaging API (V1), select the three dots icon (), then Manage API in Google Cloud Console, which will open in a new browser window or tab:

   

6. Select Enable:

   

7. Close the Google Cloud Console window or tab.

If you are setting up token authentication after previously using server key auth, you must give your Firebase service account the cloudmessaging.messages.create permission to send notifications and data messages through the FCM HTTP API and Admin SDK. You can create and assign a custom role for the single permission or you can assign the Firebase Cloud Messaging API Admin role, which includes the permission and other permissions.

For additional information, see Google references:

• Firebase Cloud Messaging permissions  in Firebase IAM permissions
• Firebase Cloud Messaging API Admin in IAM basic and predefined roles reference
• Custom roles in About IAM access roles: Roles and permissions

To create and assign a custom role for the single permission:

1. Log in to the Google Cloud console .
2. Select IAM & ADMIN.
3. If you are not viewing the permissions for the correct project, select the correct project from the menu in the header.
4. Create the role:
   1. Select Roles in the sidebar.
   2. Select () CREATE ROLE.
   3. Add a meaningful title, description, and ID, then select a role launch stage.
   4. Select () ADD PERMISSIONS.
   5. Enter property name cloudmessaging.messages.create, check the box for it in the list, then select ADD.

      

   6. Select CREATE.
5. Assign the role to your service account:
   1. Select IAM in the sidebar.
   2. Under View by Principals, select the pencil icon () next to firebase-service-account@firebase-sa-management.iam.gserviceaccount.com.
   3. Select () ADD ROLE or () ADD ANOTHER ROLE.
   4. Select the Select a role menu, then select your custom role from the Quick Access list or type its name created and select it from the results.
   5. Select Save.

To assign the Firebase Cloud Messaging API Admin role that includes the permission:

1. Log in to the Google Cloud console .
2. Select IAM & ADMIN.
3. If you are not viewing the permissions for the correct project, select the correct project from the menu in the header.
4. Under View by Principals, select the pencil icon () next to firebase-service-account@firebase-sa-management.iam.gserviceaccount.com.
5. If the role “Firebase Cloud Messaging API Admin” is not already listed:
   1. Select () ADD ROLE or () ADD ANOTHER ROLE.
   2. Select the Select a role menu, then type “Firebase Cloud Messaging API Admin” and select it from the results.
       Warning

      Be sure to select Firebase Cloud Messaging API Admin, not Firebase Cloud Messaging Admin.

   3. Select Save.

Next, generate a private key:

1. Return to the Firebase console  and select your project.
2. In the sidebar, select the gear icon (), then Project settings.
3. Select the Service accounts tab.
4. Under Firebase Admin SDK, select Generate new private key, then Generate key. The key will download as .json file with a name like project--4173162SAMPLE949879-firebase-adminsdk-0ddvl-1d0bc7bacb.json. Make sure to store this file in a secure location.

Now you can configure the Android channel for your project in Airship:

1. Go to Settings.
2. Under Channels, select Mobile Apps, then Android.
3. For Application ID, select Edit, enter your application ID , then select Save.
4. For Firebase Cloud Messaging (FCM) Token-based authentication, select Edit and upload your Firebase private key file, then select Save.

FCM server key auth

First, enable the Cloud Messaging API for your Firebase project:

1. Log in to the Firebase console .
2. Either create a new project or select an existing project that you want to configure with Airship.
3. In the sidebar, select the gear icon (), then Project settings:

   

4. Select the Cloud Messaging tab.
5. For Cloud Messaging API (Legacy), select the three dots icon (), then Manage API in Google Cloud Console, which will open in a new browser window or tab:

   

6. Select Enable:

   

7. Close the Google Cloud Console window or tab.

Next, get your server key:

1. Return to the Firebase console  and select your project.
2. In the sidebar, select the gear icon (), then Project settings.
3. Select the Cloud Messaging tab.
4. Under Cloud Messaging API (Legacy), copy the Server key:

   

Now you can configure the Android channel for your project in Airship:

1. Go to Settings.
2. Under Channels, select Mobile Apps, then Android.
3. For Application ID, select Edit, enter your application ID , then select Save.
4. For Firebase Cloud Messaging (FCM) Server key authentication, select Edit, enter the server key you copied in the previous section, then select Save.

FCM HTTP v1 API FAQ

These questions and answers address Google’s FCM HTTP v1 API as it relates to Airship projects. If you have additional questions, contact Airship Support  or your account manager.

Do I need to update my SDK and/or release a new version of my app?

No. This is a server-side change only.

What changed in Airship?

In January 2024, Airship added support for Android apps using the Firebase Cloud Messaging HTTP v1 API.

Why did Airship make this change?

Historically, Airship has used Google’s Cloud Messaging API for sending notifications to Android devices. This legacy API uses HTTP and XMPP protocols for sending and receiving messages and server keys for authorization. While this API is still technically supported by Google, it was replaced in 2017 with the FCM HTTP v1 API. On June 20, 2023, Google deprecated the legacy FCM APIs that Airship uses (namely https://fcm.googleapis.com/fcm/send) and announced they would remove support for these legacy APIs in June 2024.

What are the benefits of this newer API?

The newer FCM API includes a variety of updates, such as using the HTTP v1 protocol and replacing the server key authentication used in the old API with short-lived access tokens that follow the OAuth2  security model. These tokens provide better security than server key since, in the event of tokens becoming public, they can only be used for about an hour before they expire.

How does the API change affect Airship?

The API change is only related to the delivery of Android push notifications. It does not affect message content or other message types or platforms.

Which Airship projects are affected by the API change?

Any project configured for FCM that is used to send Android push notifications.

Do I need to do anything, or does Airship handle moving to the new API?

Yes, you need to set up token-based authentication for FCM. We updated our services to use the new API, but your project cannot start using it until authenticated.

What exactly do I need to do?

Follow the steps in FCM token auth (recommended) above to set up token-based authentication for FCM in your Airship project. You will:

1. Enable the Firebase Cloud Messaging API (V1) for your Firebase project.
2. Generate a private key and download the file.
3. Upload the file in your Airship project settings.

After completing the steps, your Airship project will immediately switch to using the new API to send Android push notifications.

Do I need to update authentication configuration for all of my projects at once?

No. It is up to you if you want to update all your projects in quick succession.

How long do I have to switch to token-based authentication?

You must make this change before June 2024.

When will Airship remove server key authentication?

Airship will remove server key authentication for Android projects after Google removes their Cloud Messaging API in June 2024.

HMS

First you need to configure your app information in AppGallery Connect, then you can enter your HMS client ID and secret in Airship.

• If you have not yet configured your app, complete the steps in Huawei’s Configuring App Information in AppGallery Connect . In the section Configuring the Signing Certificate Fingerprint , make sure to copy the values for Client ID and Client secret.

• If you already configured your app information in AppGallery Connect, get your client ID and secret:

  1. Log in to AppGallery Connect .
  2. Select My projects, then select the project that contains the app you configured with Airship, then select the Airship app.
  3. Under App information, copy the values for Client ID and Client secret.

     

  These steps are also provided in Viewing Basic App Information  in Configuring App Information in AppGallery Connect.

Now you can configure the Android channel for the project in Airship:

1. Go to Settings.
2. Under Channels, select Mobile Apps, then Android.
3. Under Huawei Mobile Services (HMS), enter your Huawei client ID and client secret in the Huawei app ID and Huawei app secret fields.
4. Select Add Android.

Amazon channel configuration

To configure Amazon channels, you must configure Amazon Device Messaging (ADM).

First, follow Amazon’s documentation  to obtain your OAuth Credentials and API Key.

Then you can configure the Amazon channel for the project in Airship:

1. Go to Settings.
2. Under Channels, select Mobile Apps, then Amazon.
3. Enter your OAuth credentials for the Client ID and Client secret.
4. Select Save.