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)

Apple’s token authentication for APNs uses two key types: team-scoped and topic-scoped. Understanding their difference is key for Airship setup:

• Team-scoped keys: Broad and simple

  • Team-wide access: One key for all your team’s apps
  • Limited number: Maximum two per environment (Sandbox/Production)
  • Simpler setup and easier management

• Topic-scoped keys: Granular and more secure

  • App-specific access: Key for specific apps/topics only
  • Higher number: Up to 200 per environment (Sandbox/Production)

To get started, register a new key:

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. Continue 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.
6. In the sidebar, select Keys.
7. Select the plus icon ().
8. Enter a unique key name.
9. Enable Apple Push Notifications service (APNs).
10. Select Configure.
11. (For team-scoped token auth) Select Sandbox & Production for the environment and Team Scoped (All Topics) for Key Restriction.

    

12. (For topic-scoped token auth) Select Sandbox for development apps or Production for production apps in the environment menu and Topic Specific for Key Restriction, then:
    1. Select the specific apps/topics that this key should be allowed to send notifications to.
       

       

    2. Select topics you wish to add to your scope, then Done.

       

13. Select Save, then Continue, then Register.
14. Note the Key ID, then select Download to save the key in .p8 format.

    

     Important

    For team-scoped keys: 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 team-scoped 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.

    For topic-scoped keys: You may create up to 200 topic-scoped APNs keys per environment. If you want to reuse a key across multiple Airship projects or apps, store it securely. Apple will not let you re-download it later, and Airship will not make it available for download once uploaded.

Finally, configure your iOS channel in Airship:

1. Go to Settings.
2. Under Channels, select Mobile Apps or Mobile App & Web.
3. Under Platforms, select iOS.
4. For Token-based authentication, select Edit.
5. Under Signing key, upload your .p8 file.
6. Enter your Team, Bundle, and Key IDs.
7. 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 or Mobile App & Web.
3. Under Platforms, select iOS.
4. For Certificate-based authentication, select Edit.
5. Enter the certificate password and upload the .p12 file.
6. 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 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.

• To check your current limit:

  1. Log in to the Google Cloud console .
  2. Select your FCM project, then APIs & Services, then Firebase Cloud Messaging API then Quotas & System Limits, or go directly to https://console.cloud.google.com/apis/api/fcm.googleapis.com/quotas .
  3. In the table, see the value for Send requests per minute.

• To request a rate limit increase, contact Firebase Support . See When to reach out to FCM  in Google’s Best practices when sending FCM messages at scale.

FCM token auth

Firebase projects use Google’s FCM HTTP v1 API, which uses short-lived access tokens that follow the OAuth2  security model. In the event of tokens becoming public, they can only be used for about an hour before they expire.

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 or Mobile App & Web.
3. Under Platforms, select Android.
4. For Application ID, select Edit, enter your application ID , then select Save.
5. For Firebase Cloud Messaging (FCM) Token-based authentication, select Edit and upload your Firebase private key file, then select Save.

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 or Mobile App & Web.
3. Under Platforms, select Android.
4. Under Huawei Mobile Services (HMS), enter your Huawei client ID and client secret in the Huawei app ID and Huawei app secret fields.
5. Select Add Android.

Fire OS channel configuration

To configure Fire OS 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 Fire OS channel for the project in Airship:

1. Go to Settings.
2. Under Channels, select Mobile Apps or Mobile App & Web.
3. Under Platforms, select Fire OS.
4. Enter your OAuth credentials for the Client ID and Client secret.
5. Select Save.