Push / App Messaging

To setup the Push or App Messaging channels you need to configure your authentication so that we can recognise your app users, and if you want to use the native push channels, such as APNS and FCM, then follow the instructions below to do this:

Authentication Setup

To see and configure your App Messaging authentication open your API Space in the portal and select the Channels page from the menu on the left, and find the Messenger section (highlighted in green below)

App Messaging is a secure messaging channel and therefore requires you to authenticate users prior to them being able to use App Messaging. Authentication can be performed by any authentication server or service that can issue a JWT (JSON Web Token). There are plenty of authentication platforms available to use that can issue tokens for your authenticated users, or use your existing systems. More information on how to create a JWT can be found on this website.

Fully Authenticated

To configure App Messaging to be fully authenticated utilising your systems JWT tokens click on the Authentication button in the App Messaging section.

Now fill out the fields on the form so that we can understand and verify your JWT tokens; the fields are:

Anonymous Authentication

App Messaging requires a JWT token in order to recognise users, but if you want to support anonymous users this is still possible by simply creating a unique user Id (such as a GUID) for them and issuing them a JWT. This process is sometimes referred to as self issued tokens.

There are two ways of creating a JWT for anonymous users, you can:
###Use the Session API to create a JWT
This is a convenient way to create an anonymous user JWT, simply call the Session API to generate an anonymous JWT. You can pass a user id, which could be a GUID, and a nonce to ensure the JWT is the one you requested. Note: The profile id for the anonymous user will be the passed user id prefixed with anon_

Self Issued JWT

With this option you must create a valid JWT matching the settings you entered into the App Messaging configuration; you have total control of the user id and claims. There are plenty of code examples of how to create JWT online, and a lot of good information and code libraries can be found at the JWT home page. Alternatively you can use our Session API to create an anonymous JWT for you.

Push Configuration

To see and configure your App Messaging native push channels open your API Space in the portal and select the Channels page from the menu on the left, and find the Messenger section (highlighted in green below)

If you are using our App Messaging SDK's in native apps the native push channels for the platforms (APNS and FCM) will need to be configured using the instructions below:

Android FCM Setup

Follow these instructions to configure FCM for App Messaging to use for native push notifications:

1. Open the Firebase Console
2. If you haven’t created an API project yet, click Create Project
3. Find your Firebase project and click Project Name
4. Click the setting icon and select Project Settings from the cog menu

5. Select Could Messaging tab and copy the Server Key (Highlighted in green below) from the page

6. In the Portal open the Channels page and then in the App Messaging section and click on the Android logo button. Now click the FCM Credentials button. In the pop-up fill in the form with your Android package name and FCM Server key from step 5 above.

👍

Complete

Now ensure you have integrated the App Messaging SDK, so that you can test you settings.

Apple APNS Setup

You have two options for setting up APNS you can use either the newer APNS token based authentication system, or individual APNS certificate per app bundle. Follow the instructions below for your chosen APNS option to complete the setup in the portal:

📘

We recommend using APNS tokens

The newer APNS token based authentication is our preferred configuration for APNS as it will work for apps published under a Apple Developer account, and does not expire unlike the APNS certificates that expire annually.

APNS Tokens

Follow these instructions to configure APNS for App Messaging to use APNS tokens for native push notifications:

1. Log into your Apple Developers Portal
2. Select the Certificates, IDs & Profiles option
3. Select the Keys > All option
4. Click the + button to create a new key
5. Enter an appropriate name for the key and ensure the Apple Push Notifications service (APNs) option is selected
6. Create the key
7. Download the key and store securely; also note down the Key ID displayed
8. Now log into the Portal
9. Open the Channels page and in the App Messaging section and select the Apple logo button. In the next screen select the APNS Token button and you will see the pop-up below:

10. Click on the Upload private key area
11. Select your APNS Private key file (p8 file) you downloaded in step 7 and upload the file
12. Enter your Key ID also retrieved in step 7
13. Finally enter your Team ID which can be found in the Apple Developers Portal under the Membership section
14. Click Save to confirm the settings.

👍

All done

Now ensure you have integrated the App Messaging SDK, so that you can test you settings.

APNS Certificates

🚧

Remember APNS certificates need refreshing annually!

APNS certificates are only valid for one year and therefore will need a new one generated annually for each app and then the p12 certificate extracted and uploaded to the portal. Please ensure you have reminders set to do this in good time prior to your certificate expiry.

Follow these instructions to configure APNS for App Messaging to use APNS certifcates for native push notifications:

📘

Already have an APNS certificate?

If you already have an APNS certificate you can jump to step 6

The following is a complete guide on generating the required certificates in your App Developer account, with the following steps:

1. Create a new App ID or find your application
2. Request the certificate
3. Configuring an App ID for Push Notifications
4. Download the certificate
5. Create the provisioning profile
6. Upload your APNS certificate

Create a new App ID or find your application

📘

If you already have an App ID in the Apple Developer Member Center, follow these steps. If you do not, skip to step 2.

1. Log in to the Apple Developer Member Center
2. Click on Identifiers under iOS Apps and locate your application in the list.

3. If you haven't registered an App ID yet, click the + symbol and fill out the form, making sure to check the Push Notifications checkbox.

📘

Wildcard IDs cannot use the push notification service.

4. Register a new App ID. Enter your App ID Description (Ex: “PushAppID”), and select an App ID Prefix. In the App ID Suffix section choose Explicit App ID, and provide the correct Bundle Identifier in the form com.company.application (i.e.: com.mobiledonky.MyPushApp).

Request the certificate

1. Generate a certificate request file using 'Keychain Access' on your OS X Machine (.)

👍

Hint

Tap cmd + space to bring up Spotlight

2. Select Keychain Access >> Certificate Assistant >> Request a Certificate From a Certificate Authority

3. Enter the required information and click the Saved to disk option. Click Continue

4. Save the certificate request using the suggested name and click Save >> Done on the next screen.

Configuring an App ID for Push Notifications

Once an App ID is created, you need to configure it for push notifications.

1. Click Settings to configure Push Notifications for your App ID

2. Check the box to activate Push Notifications for the App ID and click the Create Certificate link displayed on the right

3. You will now see the Apple Push Notification service SSL Certificate Assistant screen. Click Continue

4. Click the Choose File button to locate the Certificate Request file that you have saved earlier. Click *Generate

5. Your SSL Certificate will now be generated. Click Continue. Click Done to continue

📘

The same process above applies when generating the production certificate.

Download the certificate

1. Now you can download the certificate, click the Download button

2. The SSL Certificate that you download is named aps_developer_identity.cer. Double-click on it to install it in the Keychain Access application.

📘

The SSL certificate will be used by your provider application so that it can contact the APNs to send push notifications to your applications.

3. Launch Keychain Assistant and from the 'login' keychain, filter by the Certificates category.

🚧

Private Key Only

In the following step, ensure you only export the private key (child item) not the whole certificate. Only the private key is require for Inbox to connect to APNS.

4. Expand “Apple Development/Production iOS Push Services” option then right click on “Apple Development iOS Push Services”
5. Export “Apple Development/Production iOS Push Services ...″. Save this as apns-dev-cert.p12.
6. Enter the password for exporting (this is an optional field)

👍

This is the file that you need to upload to Inbox Control >> App Space Settings >> Push using your password (if created) and Bundle ID; see step 6 for more details

Create the provisioning profile

1. Click on the Provisioning profiles tab in the iOS Apps module to create a provision profile.

2. Click the + symbol to create a new provisioning profile

3. Select a type of the provisioning profile you need to create and click on Continue button to continue the creation.

4. Select App ID you are creating the provisioning profile for.

5. Select the certificates you wish to include in this provisioning profile and click the Continue button

6. Select the devices you wish to include in this provisioning profile and click on Continue button.

7. Input the Provisioning profile name and click on Generate button to generate the profile

8. After the generating of the Provisioning Profile was finished screen with the info and available options appears. Click the Download button to download the Provisioning profile

📘

Also you can download the Provisioning profile later. Open a list with all Provisioning profiles and choose the required. Additional options become available.

9. After you click Download the provisioning profile will be downloaded you then need to open the file.
10. Open your application in Xcode, go to Project structure, select *.plist file and make sure that the Bundle ID in your Xcode projects info.plist matches that of the Provisioning profile.

11. Go to Build Settings >> Code Signing >> Code Sign Identity >> Provisioning Profile and select your Provision Profile

12. Now just run the application! Thats all.

Upload your APNS certificate

1. Login to the Portal and open the Channels page and look at the App Messaging section
2. Click on the Apple logo button, and then select the APNS Certificates button
3. Click on the Upload certificate area
4. Select your certificate file in the file dialogue
5. Enter your certificates private key password
6. Click Save

👍

Complete

Now ensure you have integrated the App Messaging SDK, so that you can test you settings.