Configure Mobile Channels and Push Providers in the Airship Dashboard
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.
Go to Account, then Membership details, then note your Team ID.
Go to Program Resources, then Certificates, IDs & Profiles, then Identifiers.
If you already registered an iOS App ID:
Select its name in the list of App IDs.
Note the Bundle ID for the app.
Enable Push Notifications.Enabling push notifications for an iOS app ID
If Push Notifications was already enabled, select All Identifiers at the top of the page to go back. Otherwise, select Save.
Go to step 6 below.
If you have not already registered an iOS App ID, add one now:
Select the plus icon (), then select App IDs.Adding an iOS app identifier
Select Continue.
Fill out the Register an App ID form and enable Push Notifications. Also note the Bundle ID you enter.Registering an app ID
Select Continue, then Register.
Continue to step 6 below.
Register a new key:
In the sidebar, select Keys.
Select the plus icon ().
Enter a unique key name.
Enable Apple Push Notifications service (APNs).Registering a new key
Select Continue, then Register.
Note the Key ID, then select Download to save the key in .p8 format.Getting your key ID and downloading the key
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:
Go to Account, then Program Resources, then Certificates, IDs & Profiles, then Identifiers.
If you already registered an iOS App ID, select its name in the list of App IDs, then go to step 5 below.
If you have not already registered an iOS App ID, add one now:
Select the plus icon (), then select App IDs.Adding an iOS app identifier
Select Continue.
Fill out the Register an App ID form and enable Push Notifications.Registering an app ID
Select Continue, then Register.
Select your app’s name in the list of App IDs, then continue to step 5 below.
Under Capabilities, enable Push Notifications, then select Configure. The button is labeled Edit if it was previously configured.enabling Push Notifications for an App ID
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.
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:
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.
Select Download and save the file for use in the next step.
Open the certificate you downloaded in the previous step.
It should open in the Keychain Access app and be
listed in My Certificates.
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.
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:
Go to Settings.
Under Channels, select Mobile Apps, then iOS.
For Certificate-based authentication, select Edit.
Enter the certificate password and upload the .p12 file.
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.
Important
For any Airship project configured for FCM that is used to send Android push notifications, you must move to token-based authentication by July 2024.
Why do I have to do this?
Google replaced the Cloud Messaging API with the FCM HTTP v1 API, which uses token-based authentication. 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 to switch to token-based authentication?
Request enabling token-based authentication for your Airship account.
Enable the Firebase Cloud Messaging API (V1) for your Firebase project.
Generate a private key and download the file.
Upload the file in your Airship project settings.
What happens after I set up token-based authentication?
Your Airship project will immediately switch to using the new API to send Android push notifications.
For additional information, see the FAQ on this page.
FCM rate limit
The Firebase Cloud Messaging API has a default rate limit of 600,000 requests per minute. If your project reaches that limit, Airship will retry after one minute. You may want to request a rate limit increase if you send to large volume audiences when sending time-sensitive messaging such as breaking news.
Either create a new project or select an existing project that you want to configure with Airship.
In the sidebar, select the gear icon (), then Project settings:Selecting Firebase Project settings
Select the Cloud Messaging tab.
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:Managing the API
Select Enable:Enabling the Firebase Cloud Messaging API
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:
In the sidebar, select the gear icon (), then Project settings.
Select the Service accounts tab.
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:
Go to Settings.
Under Channels, select Mobile Apps, then Android.
For Application ID, select Edit, enter your application ID, then select Save.
For Firebase Cloud Messaging (FCM) Token-based authentication, select Edit and upload your Firebase private key file, then select Save.
FCM server key auth
Important
If you are configuring FCM for a project for the first time, do not use server key authentication. It will not be supported after July 2024. Follow the steps for token-based authentication instead.
First, enable the Cloud Messaging API for your Firebase project:
Either create a new project or select an existing project that you want to configure with Airship.
In the sidebar, select the gear icon (), then Project settings:Selecting Firebase Project settings
Select the Cloud Messaging tab.
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:Managing the API
In the sidebar, select the gear icon (), then Project settings.
Select the Cloud Messaging tab.
Under Cloud Messaging API (Legacy), copy the Server key:Copying the server key
Now you can configure the Android channel for your project in Airship:
Go to Settings.
Under Channels, select Mobile Apps, then Android.
For Application ID, select Edit, enter your application ID, then select Save.
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 July 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:
Enable the Firebase Cloud Messaging API (V1) for your Firebase project.
Generate a private key and download the file.
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 July 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 July 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.
Select My projects, then select the project that contains the app you configured with Airship, then select the Airship app.
Under App information, copy the values for Client ID and Client secret.Retrieving the client ID and secret from AppGallery Connect
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:
Go to Settings.
Under Channels, select Mobile Apps, then Android.
Under Huawei Mobile Services (HMS), enter your Huawei client ID and client secret in the Huawei app ID and Huawei app secret fields.
Select Add Android.
Amazon channel configuration
To configure Amazon channels, you must configure Amazon Device Messaging (ADM).
Note
While you will not need in-depth knowledge of Amazon’s ADM platform
in order to use ADM for push notifications, we recommend that you
review Amazon’s Overview of Amazon Device Messaging before continuing.