# Configuring Mobile Channels Configure mobile channels and push providers in the Airship dashboard. Configuration information and steps are provided for iOS, Android, and Fire OS. ## iOS channel configuration To configure an iOS channel, you must configure the Apple Push Notification Service (APNs). To do this, you can either use token or certificate authentication. Use token auth to simplify setup and to avoid having to renew your certificate every year. ### APNs token and certificate authentication Airship uses token-based authentication for APNs when configured for the iOS channel. When token-based authentication is not configured, Airship uses certificate authentication instead. The authentication choice depends on what you have configured, not on fallback from token to certificate. If token auth is configured but becomes invalid or stops working, Airship does not automatically use your certificate. As a result, the iOS channel may be disabled until you correct your authentication configuration in the Airship dashboard. For existing projects: * Leave your certificate in place while migrating to token-based authentication. If you remove your certificate before token auth is working, you may be unable to send messages until your credentials are valid. * Once you have confirmed that token auth is working, you may let the certificate expire or revoke it in the Apple Developer Member Center. ### Production versus development projects When creating your certificate or token, you must choose which environment the application on your device should use. Unlike Android, APNs uses two different environments for push notifications depending on the type of app you are using: | Environment | Description | | --- | --- | | **Sandbox** | The Sandbox environment is intended for applications that are being developed and tested directly off of a computer. | | **Production** | The Production environment is for applications that are distributed via the App Store or any ad hoc platform like Test Flight. | When you [create or edit an Airship project](https://www.airship.com/docs/guides/getting-started/setup/#create-a-messaging-project) (and thus its application record on our server), you must select its type, which directly affects which APNS environment it will communicate with: | Project type | Description | Relationship with APNs environment | | --- | --- | --- | | **Test** | Development for sending test messages | A Test project only sends APNs push notifications to the Sandbox environment | | **Live** | Production for sending messages to users | A Live project only sends APNs push notifications to the Production environment | Apple treats the production and development servers separately, so a device token for a test project will not work in a production project. 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:** * There is no way to change the Test/Live setting after an Airship project has been created. You will need to make a new project to switch environments. When these environments are not aligned, you will see errors in your error console, and typically the Push Address will be removed from the channel. > > * 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](https://support.airship.com/hc/en-us/articles/6613974842523-iOS-Production-Launch-Checklist)). > > * 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. While your app's code is pointing to an Airship app key that is set as **Test**, do not: > 1. Submit to the App Store, or > 1. Test notifications on an ad hoc build. ### Configure 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](https://developer.apple.com/). 1. Go to **Account**, then **Membership details**, then note your **Team ID**. 1. Go to **Program Resources**, then **Certificates, IDs & Profiles**, then **Identifiers**. 1. If you already registered an iOS App ID: 1. Select its name in the list of App IDs. 1. Note the **Bundle ID** for the app. 1. Enable **Push Notifications**. ![Enabling push notifications for an iOS app ID](https://www.airship.com/docs/images/creating-app2_hu_7ef0bbaf2358105d.webp) *Enabling push notifications for an iOS app ID* 1. If Push Notifications was already enabled, select **All Identifiers** at the top of the page to go back. Otherwise, select **Save**. 1. Continue to step 6 below. 1. If you have not already registered an iOS App ID, add one now: 1. Select the plus icon ( ), then select **App IDs**. ![Adding an iOS app identifier](https://www.airship.com/docs/images/creating-app0_hu_fa8b12bbff72282.webp) *Adding an iOS app identifier* 1. Select **Continue**. 1. Fill out the **Register an App ID** form and enable **Push Notifications**. Also note the **Bundle ID** you enter. ![Registering an app ID](https://www.airship.com/docs/images/creating-app1_hu_5784ce6faf347971.webp) *Registering an app ID* 1. Select **Continue**, then **Register**. 1. In the sidebar, select **Keys**. 1. Select the plus icon ( ). 1. Enter a unique key name. 1. Enable **Apple Push Notifications service (APNs)**. 1. Select **Configure**. 1. (For team-scoped token auth) Select **Sandbox & Production** for the environment and **Team Scoped (All Topics)** for Key Restriction. ![Configuring a team-scoped key](https://www.airship.com/docs/images/token-auth-team-scoped_hu_3f21037e6124fce9.webp) *Configuring a team-scoped key* 1. (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. ![Configuring a topic-scoped key](https://www.airship.com/docs/images/token-auth-topic-scoped_hu_dee79f82fa24c18c.webp) *Configuring a topic-scoped key* 1. Select topics you wish to add to your scope, then **Done**. ![Selecting topics](https://www.airship.com/docs/images/token-auth-topic-scoped-topic-selection_hu_d521ade74dcd4bc4.webp) *Selecting topics* 1. Select **Save**, then **Continue**, then **Register**. 1. Note the **Key ID**, then select **Download** to save the key in .p8 format. ![Getting your key ID and downloading the key](https://www.airship.com/docs/images/download-key_hu_a3f73b0e05fc0130.webp) *Getting your key ID and downloading the key* > **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. Next to your project name, select the dropdown menu ( ), then **Settings**. 1. Under **Channels**, select **iOS**. 1. For **Token-based authentication**, select **Edit**. 1. Under **Signing key**, upload your .p8 file. 1. Enter your Team, Bundle, and Key IDs. 1. Select **Save**. ### Configure certificate auth 1. Log in to the [Apple Developer Member Center](https://developer.apple.com/). 1. Go to **Account**, then **Program Resources**, then **Certificates, IDs & Profiles**, then **Identifiers**. 1. If you already registered an iOS App ID, select its name in the list of App IDs, then go to step 5 below. 1. If you have not already registered an iOS App ID, add one now: 1. Select the plus icon ( ), then select **App IDs**. ![Adding an iOS app identifier](https://www.airship.com/docs/images/creating-app0_hu_fa8b12bbff72282.webp) *Adding an iOS app identifier* 1. Select **Continue**. 1. Fill out the **Register an App ID** form and enable **Push Notifications**. ![Registering an app ID](https://www.airship.com/docs/images/creating-app1_hu_5784ce6faf347971.webp) *Registering an app ID* 1. Select **Continue**, then **Register**. 1. Select your app's name in the list of App IDs, then continue to step 5 below. 1. 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](https://www.airship.com/docs/images/configure-push_hu_c2a845fd1bae4062.webp) *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. 1. Select **Create Certificate**: ![Creating a certificate for Push Notifications](https://www.airship.com/docs/images/ssl-certs-section_hu_516f4ac8c7e1023c.webp) *Creating a certificate for Push Notifications* 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: ![Creating a new APNs SSL certificate](https://www.airship.com/docs/images/ssl-certs-universal_hu_595879e37f151706.webp) *Creating a new APNs SSL certificate* 1. Follow Apple's instructions to [create a certificate signing request](https://developer.apple.com/help/account/create-certificates/create-a-certificate-signing-request), then upload the file under **Create a New Certificate**. 1. 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. 1. Select **Download** and save the file for use in the next step. ![Downloading your APNs certificate](https://www.airship.com/docs/images/download-cert_hu_dd3be2b79175a02d.webp) *Downloading your APNs certificate* 1. Open the certificate you downloaded in the previous step. It should open in the Keychain Access app and be listed in My Certificates. ![The certificate in Keychain Access](https://www.airship.com/docs/images/keychain-cert_hu_40601819eb30f4ea.webp) *The certificate in Keychain Access* 1. Select the certificate in the list, then from the **File** menu, select **Export Items...**. ![Exporting the certificate as a .p12 file](https://www.airship.com/docs/images/p-export-p12_hu_853f430fb03d4b60.webp) *Exporting the certificate as a .p12 file* > **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. 1. Save the file in the Personal Information Exchange (.p12) format. ![Saving the certificate in .p12 format](https://www.airship.com/docs/images/export-filename_hu_a67ac4824a950386.webp) *Saving the certificate in .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. Next to your project name, select the dropdown menu ( ), then **Settings**. 1. Under **Channels**, select **iOS**. 1. For **Certificate-based authentication**, select **Edit**. 1. Enter the certificate password and upload the .p12 file. 1. 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](https://console.cloud.google.com/). 1. 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. 1. In the table, see the value for **Send requests per minute**. * To request a rate limit increase, [contact Firebase Support](https://firebase.google.com/support). See [When to reach out to FCM](https://firebase.google.com/docs/cloud-messaging/scale-fcm#when-reach) in Google's *Best practices when sending FCM messages at scale*. ### Configure FCM token auth Firebase projects use Google's FCM HTTP v1 API, which uses short-lived access tokens that follow the [OAuth2](https://en.wikipedia.org/wiki/OAuth) security model. In the event of tokens becoming public, they can only be used for about an hour before they expire. > **Important:** In July 2024, Google replaced the Cloud Messaging API with the FCM HTTP v1 API. This change affected sending Android push notifications. We updated our services to use the new API, but your project cannot start using it until authenticated. > > If your Airship project has not yet moved to token-based authentication, complete the setup steps that follow this note. You will enable the Firebase Cloud Messaging API (V1) for your Firebase project, generate a private key and download the file, and upload the file in your Airship project settings. > > Your Airship project will immediately switch to using the new API to send Android push notifications. You do not need to update your SDK and/or release a new version of my app. This is a server-side change only. > > If you have questions, [contact Airship Support](https://support.airship.com/) or your account manager. First, enable the Firebase Cloud Messaging API (V1) for your Firebase project: 1. Log in to the [Firebase console](https://console.firebase.google.com/). 1. Either create a new project or select an existing project that you want to configure with Airship. 1. In the sidebar, select the gear icon (), then **Project settings**: ![Selecting Firebase Project settings](https://www.airship.com/docs/images/android/fcm-project-settings_hu_f1e317b06e57c88d.webp) *Selecting Firebase Project settings* 1. Select the **Cloud Messaging** tab. 1. 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](https://www.airship.com/docs/images/android/fcm-token-enable-api_hu_2d8cc25c05392763.webp) *Managing the API* 1. Select **Enable**: ![Enabling the Firebase Cloud Messaging API](https://www.airship.com/docs/images/android/fcm-enable-api_hu_85291aaf1c2038dc.webp) *Enabling the Firebase Cloud Messaging API* 1. 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](https://firebase.google.com/docs/projects/iam/permissions/#messaging) in *Firebase IAM permissions* * [Firebase Cloud Messaging API Admin](https://cloud.google.com/iam/docs/understanding-roles#firebasecloudmessaging.admin)in *IAM basic and predefined roles reference* * [Custom roles](https://cloud.google.com/iam/docs/roles-overview#custom)in *About IAM access roles: Roles and permissions* To get your Firebase service account: 1. Go to the [Firebase console](https://console.firebase.google.com/) and select your project. 1. In the sidebar, select the gear icon (), then **Project settings**. 1. Select **Service Accounts**. 1. In the **Firebase Admin SDK** section, see the value under **Firebase service account**. The account has the naming convention `firebase-adminsdk-@.iam.gserviceaccount.com`. To create and assign a **custom role** for the single permission: 1. Log in to the [Google Cloud console](https://console.cloud.google.com/). 1. Select **IAM & ADMIN**. 1. If you are not viewing the permissions for the correct project, select the correct project from the menu in the header. 1. Create the role: 1. Select **Roles** in the sidebar. 1. Select **() CREATE ROLE**. 1. Add a meaningful title, description, and ID, then select a role launch stage. 1. Select **() ADD PERMISSIONS**. 1. Enter property name `cloudmessaging.messages.create`, check the box for it in the list, then select **ADD**. ![Adding permission to an IAM role.](https://www.airship.com/docs/images/android/fcm-iam-role-permission_hu_4f58672467df24e9.webp) *Adding permission to an IAM role.* 1. Select **CREATE**. 1. Assign the role to your service account: 1. Select **IAM** in the sidebar. 1. Under **View by principals**, select the pencil icon ( ) next to your Firebase service account. 1. Select **() ADD ROLE** or **() ADD ANOTHER ROLE**. 1. 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. 1. Select **Save**. To assign the **Firebase Cloud Messaging API Admin role** that includes the permission: 1. Log in to the [Google Cloud console](https://console.cloud.google.com/). 1. Select **IAM & ADMIN**. 1. If you are not viewing the permissions for the correct project, select the correct project from the menu in the header. 1. Under **View by principals**, select the pencil icon ( ) next to your Firebase service account. 1. If the role "Firebase Cloud Messaging API Admin" is not already listed: 1. Select **() ADD ROLE** or **() ADD ANOTHER ROLE**. 1. 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**. 1. Select **Save**. --- Next, generate a private key: 1. Return to the [Firebase console](https://console.firebase.google.com/) and select your project. 1. In the sidebar, select the gear icon (), then **Project settings**. 1. Select the **Service accounts** tab. 1. 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. Next to your project name, select the dropdown menu ( ), then **Settings**. 1. Under **Channels**, select **Android**. 1. For **Application ID**, select **Edit**, enter your [application ID](https://developer.android.com/build/configure-app-module), then select **Save**. 1. For **Firebase Cloud Messaging (FCM) Token-based authentication**, select **Edit** and upload your Firebase private key file, then select **Save**. ### Configure 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](https://developer.huawei.com/consumer/en/doc/HMSCore-Guides/android-config-agc-0000001050170137). In the section [Configuring the Signing Certificate Fingerprint](https://developer.huawei.com/consumer/en/doc/HMSCore-Guides/android-config-agc-0000001050170137#section1159841225116), 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](https://developer.huawei.com/consumer/en/console). 1. Select **My projects**, then select the project that contains the app you configured with Airship, then select the Airship app. 1. Under **App information**, copy the values for **Client ID** and **Client secret**. ![Retrieving the client ID and secret from AppGallery Connect](https://www.airship.com/docs/images/android/hms-auth_hu_9088aab7d3ddfd47.webp) *Retrieving the client ID and secret from AppGallery Connect* These steps are also provided in [Viewing Basic App Information](https://developer.huawei.com/consumer/en/doc/HMSCore-Guides/android-config-agc-0000001050170137#section125831926193110) in *Configuring App Information in AppGallery Connect*. Now you can configure the Android channel for the project in Airship: 1. Next to your project name, select the dropdown menu ( ), then **Settings**. 1. Under **Channels**, select **Android**. 1. Under **Huawei Mobile Services (HMS)**, enter your Huawei client ID and client secret in the **Huawei app ID** and **Huawei app secret** fields. 1. Select **Add Android**. ## Fire OS channel configuration To configure Fire OS channels, you must configure Amazon Device Messaging (ADM). > **Note:** While you will not need in-depth knowledge of the ADM platform > in order to use ADM for push notifications, we recommend that you > review Amazon's [Overview of Amazon Device Messaging](https://developer.amazon.com/docs/adm/overview.html) before continuing. ### Configure Fire OS First, follow [Amazon's documentation](https://developer.amazon.com/docs/adm/obtain-credentials.html) to obtain your OAuth Credentials and API Key. Then you can configure the Fire OS channel for the project in Airship: 1. Next to your project name, select the dropdown menu ( ), then **Settings**. 1. Under **Channels**, select **Fire OS**. 1. Enter your OAuth credentials for the **Client ID** and **Client secret**. 1. Select **Save**.