Push Notifications

The Orb SDK supports handling push notifications when the Orb chat is not
active. This is especially useful when a bot escalates the conversation to a
human agent, but the agent takes a while to respond.

To fully setup push notifications you will need to configure the following
three components:

Android Firebase Cloud Messaging (FCM)
Apple Push Notification service (APNs)
Orb Mobile integration in your Meya app.

Note, this is not the same as the standard Orb integration used for
the web client. The Orb Mobile integration is identified by
type: meya.orb.mobile.integration - here is an example configuration.
You can still connect the Orb SDK to the Orb integration, but it will not
handle any push notifications.

Android Setup

1. Setup Firebase Cloud Messaging (FCM) on Android

Follow these instructions to add FCM to your app:
Set up a Firebase Cloud Messaging client app on Android

2. Get your Firebase Service Account Key

Open your Firebase Console
Select the project you're using for FCM
Click gear icon next to Project Overview
Go to Project settings
Click on Generate new private key
This will download a .json file to your computer

3. Add the Service Account Key to your app's vault

Copy the JSON from the .json private key file you downloaded from the Firebase
Console.
Open your app's vault in the Meya Console
Add the vault key named orb.mobile.service_account_key
Paste the JSON you copied
Click the ✓ button
Click Save

4. Add the Orb Mobile integration to your app

Add the following BFML to you app, we recommend you save this file in the
integration/orb/mobile/ folder, but you can save this anywhere.

id: integration.orb.mobile
type: meya.orb.mobile.integration
android:
  service_account_key: (@ vault.orb.mobile.service_account_key )

Note, the integration's ID is explicitly set in this example. If you do
not explicitly set the ID then Meya will use the folder path (using .
notation e.g. some/folder/file.yaml becomes some.folder.file ) as the
integration's ID.

5. Push your Meya app

If you're in the Meya Console then clicking Save will save the BFML and
push the changes to your app.

If you're using the Meya CLI then you'll need to do an explicit push:

meya push

6. Provide the FCM device token to the Orb SDK

You need to capture and pass the FCM device token to the Orb class before you
call orb.connect().
Example Orb Demo ChatActivity
Also make sure that your ChatActivity is registered in your app's
AndroidManifest.xml - example Orb Demo manifest

Any activity can then be launched from the push notification when the Orb
Mobile integration's android.click_action setting is set, here is an
example BFML configuration for the Orb Demo app:

id: integration.orb.mobile
type: meya.orb.mobile.integration
# This is optional
collect:
  location: user
# This is optional
identity_verification: (@ vault.orb.identity_verification )
android:
  service_account_key: (@ vault.orb.mobile.service_account_key )
  # This is the name of the activity you would like to launch that contains the
  # Orb SDK
  click_action: .ChatActivity

7. Test your push notifications

The best way to test push notifications is to:

Escalate to an agent (e.g. Zendesk/Front), close the chat activity and send
an agent message, or
Send a message via a webhook while the app is closed, see how to set up
a Webhook integration.

8. Consider in-app notifications

The Orb Mobile integration will only send a push notification when it detects
that the Orb is no longer active (it uses an internal heartbeat to detect
inactivity). However, your app could be in a running state which means the
push notification will not appear, and you'll need to handle
the incoming notification explicitly in a FirebaseMessagingService class.

The Orb Demo app has an example implementation of a FirebaseMessagingService
class here.

The example implementation does not do anything special other than
log the received payloads. However, it's important to note that the Orb Mobile
integration always adds the meya_integration_id key to the push notification
data payload which allows you to identify Meya notifications and handle them
separately from your own app notifications.

If you would like to still show a notification while the app is running, you
can create a notification manually as shown in the FCM quick start app
here

Note, advanced in-app push notification handling is on the Orb SDK roadmap
which will also provide features such as quick replies, buttons etc.

iOS Setup

1. Add APNs notifications to your app

First enable the Push Notifications Capability in your app
You'll need to implement the various application hooks to register the app
for push notifications and receive the APNs device token.
Example Orb Demo AppDelegate
You need to set the orb.deviceToken property before your call
orb.connect(). This can be done in the application lifecycle hook as
shown here in the Orb Demo
, or you can store it in your app state and use it later in your view
hierarchy.

Note, currently the Orb does not use method swizzling
to autoconfigure these hooks for you (this might be added in a future release), so
if you're using the Firebase SDK for iOS you'll need to disable Firebase's method
swizzling and implement these methods manually.

2. Create your APNs auth key

Open the Apple Developer Member Center
Go to Certificates Identifiers & Profiles
Go to Keys in the menu to the left
Click + icon next to the Keys title
Give your new key a name
Select Apple Push Notifications service (APNs)
Click Continue
Click Register
Click Download to download the file
Note the Key ID, you'll need this for the Orb Mobile integration config

3. Add the auth APNs credentials to your app's vault

Copy the private key from the auth key file that you downloaded.
Open your app's vault in the Meya Console
Add the vault key named orb.mobile.auth_key
Paste the auth key you copied
Click the ✓ button
Copy the Key ID from the key you created, Apple Developer Member Center / Keys
Add the vault key named orb.mobile.auth_key_id
Paste the auth key id you copied
Click the ✓ button
Copy you Apple Team ID, this is at the top right of the page, under your
login name
Add the vault key named orb.mobile.team_id
Paste the team id you copied
Click the ✓ button
Click Save

4. Add the Orb Mobile integration to your app

Add the following BFML to you app, we recommend you save this file in the
integration/orb/mobile/ folder, but you can save this anywhere.

id: integration.orb.mobile
type: meya.orb.mobile.integration
ios:
  auth_key: (@ vault.orb.mobile.auth_key )
  auth_key_id: (@ vault.orb.mobile.auth_key_id )
  team_id: (@ vault.orb.mobile.team_id )
  topic: YOUR APP BUNDLE ID
  apns_mode: dev

📘
Note
The integration's ID is explicitly set in this example. If you do
not explicitly set the ID then Meya will use the folder path (using .
notation e.g. some/folder/file.yaml becomes some.folder.file ) as the
integration's ID.

🚧
APNs Mode
The apns_mode property must be set to prod for production iOS
apps. The default apns_mode is dev, which uses the development APNs URL.

5. Push your Meya app

If you're in the Meya Console then clicking Save will save the BFML and
push the changes to the app.

If you're using the Meya CLI then you'll need to do an explicit push

meya push

6. Test your push notifications

The best way to test push notifications is to:

Escalate to an agent (e.g. Zendesk/Front), close the chat activity and send
an agent message, or
Send a message via a webhook while the app is closed, see how to set up
a Webhook integration.

7. Consider in-app push notifications

As is the case with Android, the Orb Mobile integration will only send a
push notification when it detects that the Orb is no longer active
(it uses an internal heartbeat to detect inactivity). However, your app could
be in a running state which means the push notification will not appear,
and you'll need to handle the incoming notification explicitly in your
application hook with the didReceiveNotification parameter.

The Orb Demo app has an example implementation of this hook.

The example implementation does not do anything special other than
log the received payloads. However, it's important to note that the Orb Mobile
integration always adds the meya_integration_id key to the push notification
data payload which allows you to identify Meya notifications and handle them
separately from your own app notifications.

Note, advanced in-app push notification handling is on the Orb SDK roadmap
which will also provide features such as quick replies, buttons etc.

Flutter setup

To set up push notifications, follow both the Android and iOS instructions above (implement using native code).