Push notifications

Push notifications are a convenient way to deliver short, actionable messages directly to your customers' devices. Unlike emails, push notifications are instantly available/accessible on a user's screen, ensuring they capture attention quickly.

For Orbit, you enable push notifications through a cloud messaging service like Google Firebase, which manages message delivery to app users. Once configured, you use Orbit to design and send push notification campaigns, with options for personalisation, images, and scheduling.

Key benefits:

• Send messages instantly to engage users
• Use FastStats to segment audiences based on device tokens and behaviours
• Personalise messages with user-specific data and include images for enhanced engagement

Cloud messaging¶

To send push notifications to both Android and Apple devices with Orbit, you must first set up a cross-platform cloud messaging service. We recommend using a Google Firebase project, as Firebase efficiently handles the delivery of push notifications to users' devices.

Below is an overview of prerequisites for setting up Firebase. For comprehensive instructions on adding the Firebase Admin SDK to your system, refer to the Firebase Admin Setup Documentation. This guide covers project creation, enabling messaging services, and generating the necessary configuration files.

Google Firebase project and service account¶

To set up a Google Firebase project and service account:

1. Create a Firebase Project.
2. Enable Cloud Messaging.
3. Register your app.
4. Save the configuration file (google-services.json or GoogleService-Info.plist) in a secure location accessible to your FastStats or Orbit configuration.

Device token collection¶

For Firebase to send messages to a user’s device, your app must generate and store device tokens:

Web or Mobile app integration:

• Ensure your app integrates Firebase SDK to handle token generation.
• Each device token uniquely identifies a user’s device or app session.

Token storage in FastStats:

• Map tokens to user profiles in FastStats.
• Use a dedicated variable in FastStats to store these tokens (e.g., Push Notification Token).

Push notification database in FastStats¶

The push notification database in FastStats acts as the link between Firebase and Orbit. It stores the configuration details and token mappings required to deliver notifications to the correct devices.

To configure the database:

1. Open the FastStats Configurator.
2. Click Database Management.

3. Locate or create a Push Notification Database.

   If the database does not exist, create a new one. See FastStats system SQL databases.

4. Insert a new row in the database’s Apps table:

   • Name: Enter a name for the app.

     Note

     This doesn’t need to match your Firebase project name.

   • GoogleServiceSettingsPath: Specify the file path of the Firebase JSON file downloaded earlier.

   • GoogleProjectName: Enter the exact project name from Firebase, matching the case used in the project_id field in the .json file specified in the GoogleServiceSettingsPath column.
   • GoogleAPIKey: Ensure this field contains a non-blank, non-null value.
   • Other fields: Populate any mandatory fields (e.g., connection strings). Non-essential fields can be left blank or populated with placeholder values if required.

5. Verify token storage. Ensure the FastStats system has a variable set up to store device tokens.

   This variable links users in FastStats to their devices.

6. Create a new campaign and send a push notification to a record that has a Push Notification Device Token you control. Sending a test message from Firebase will not test your Apteco configuration.

You're now ready to set up your push notification channel.

Push notification channel¶

Once Firebase and the Push Notification Database in FastStats are set up, the next step is to create and configure a push notification channel in Orbit. This channel allows you to deliver notifications to specific users via their device tokens.

To create a push notification channel:

1. Click your avatar in the top-right corner.

2. Click Application Settings.

   

3. Click Campaigning Channel Editor from the left-hand menu, then click Edit.

4. To add a new push notification channel, click + Item.

   

5. Select Push Notification Channel from the available options.

6. Provide a name for the channel (e.g., "Marketing Notifications").

7. Place the channel in an appropriate folder to help organise your workspace.

   

8. Click Create.

You’ve created your channel and can now complete the configuration.

Configure your channel¶

To configure your channel:

1. Enter the app name you specified in the FastStats Push Notification Database.

   

   Note

   This must match exactly (case-sensitive).

2. Select the variable from FastStats that stores device tokens (e.g., Push Notification Token).

   

3. Leave optional parameters, such as output settings, at their default values unless required.

You have successfully set up your push notification channel. The next step is to use this channel in your Orbit campaign journeys.

Use push notifications in campaigns¶

Push notifications in Orbit campaigns are flexible and can include personalisation, images, and scheduling.

To set up push notifications in a campaign:

1. From the Orbit home screen, click Campaigns.
2. Either select an existing campaign, or create a new one.

3. Choose a target audience. See Including and excluding audiences.

   Ensure the audience includes users with valid device tokens.

4. Click the plus icon to add a journey step where you want your push notification.

   

5. Select Push Notifications under Channels.

   

6. Click the option menu on your push notification step, then click Edit.

   

7. Give your step a meaningful name, then click Create.

This opens the side panel.

Push notification message step¶

You can now create your push notification message.

To set up your push notification message step:

1. Select the Push Notification Channel you created.

2. Enter a Title and Message.

   

   Tip

   Keep the text concise and engaging.

3. Add content fields to map any personalisation variables (e.g., ‘Actual ForeName’) to use in your message.

   

   See Message personalisation.

4. Specify any personalisation content fields (e.g., {}).

   

5. Use a variable named image to add an image to the notification. This is the thumbnail which appears to the left of the notification.

   

   • Ensure the variable points to a valid image URL or file path
   • Verify that the image format is compatible with the app receiving the notification

   Note

   If your app supports these settings, you can also add Badge and Sound variables.

   • Badge is the symbol which appears on your device front screen to tell you there is a new notification from the app
   • Sound is the tone that plays on your device when the notification arrives

6. Preview the notification with a test campaign run to ensure personalisation and images appear as expected.

7. Save, publish, and set a schedule for your campaign.

You have successfully used push notifications in your Orbit campaign.