Handle Push Notifications - KaleyraVideo/VideoAndroidSDK GitHub Wiki

We highly recommend to implement push notifications in your app in oder to receive incoming calls even when the app is killed.

• Doze mode requires highPriority in FCM (Android 6.0+) for more info
• In China FCM does not work (you can use Pushy, Baidu or similar services)
• Chinese mobile phones(Huawei, Xiaomi, Oppo, Vivo, LeTV, IQOO, Asus, ...) have security settings that need to be handled by the end-user. You should show a dialog to tell the user that the application will need autoBoot, notifications shown, shown on lock-screen and power optimizations. This settings may not be required if your app is already in the white-list of the PlayStore and Chinese producers. You may find useful the following links
  • https://dontkillmyapp.com/
  • https://github.com/DoubleDotLabs/doki
  • https://github.com/judemanutd/AutoStarter
  • https://github.com/WanghongLin/CRomAppWhitelist

• Listen server-side for webhook coming from Bandyer/KaleyraVideo.
• Forward the data you have received via the webhook to your Android Application with a push notification framework of your choice (FCM, OneSignal or others)

Learn more about FCM
Learn more about Huawei Push Kit
Learn more about OneSignal

• Whenever your app uses FCM or Huawei push services (or wrapper libs such as OneSignal and others) the notification payload will be automatically intercepted by the SDK and displayed.

• The only required step is to implement the abstract App Initializer KaleyraVideoInitializer as explained here, in order to configure and connect the Kaleyra Video SDK after the notification payload has been intercepted to properly prompt incoming calls to the user or display new chat messages as android notifications.

sequenceDiagram
    autonumber
    box Client
    actor Alice
    participant App
    end
    box rgb(250,250,250,0.5) NotificationService
    participant FCM/HMS
    end
    box Your Enterprise Services
    participant Cloud as Application Server
    participant Cloud_DB as Database
    end
    box rgb(250,250,250,0.5) Kaleyra Enterprise
    participant KaleyraCloud as Kaleyra Rest Api
    participant KaleyraVideoSDK
    end
    Alice-)App: Log-in
    FCM/HMS-)App: receive devicePushToken
    App-)Cloud:request_access : your_credentials, devicePushToken
    Cloud-)Cloud_DB: add devicePushToken to kaleyra_user_id
    Cloud-)KaleyraCloud:get_credentials(user_id, api_key)
    KaleyraCloud-)Cloud:kaleyra_user_access_token
    Cloud-)App: access_success: kaleyra_user_id, kaleyra_user_access_token
    App-)Alice: connected
    KaleyraCloud-)Cloud:on_call_incoming(caller_user_id,[callee_user_id],room_id...)
    Cloud-)Cloud_DB:get_listDevicePushToken(kaleyra_user_id)
    Cloud-)FCM/HMS:sendNotification(listDevicePushToken, on_call_incoming_payload)
    FCM/HMS-)App:receiveNotification(on_call_incoming_payload)
    App-)KaleyraVideoSDK:connect(kaleyra_user_id, kaleyra_user_access_token)
    Note over App,KaleyraVideoSDK: repeat steps 3-7 to get the kaleyra_user_id, kaleyra_user_access_token
    KaleyraVideoSDK-)Alice: Call Ringing Screen

The push notification payload received by your app is just a simple json containing the information your server sent to FCM.

{
   "event":"on_call_incoming",
   "room_id":"room_f61b4d202472",
   "data":{
      "initiator":"usr_123",
      "users":[
         {
            "user":{
               "userAlias":"usr_123"
            },
            "status":"invited"
         },
         {
            "user":{
               "userAlias":"usr_999"
            },
            "status":"invited"
         }
      ],
      "roomAlias":"room_f61b4d202472",
      "options":{
         "duration":0,
         "record":true,
         "recordingType":"automatic",
         "recording":"automatic",
         "creationDate":"2022-05-26T09:04:38.097Z",
         "callType":"audio_upgradable",
         "live":true
      }
   }
}

• Whenever your app uses FCM or Huawei push services (or wrapper libs such as OneSignal and others) the notification payload will be automatically intercepted by the SDK.
• The only required step is to implement the abstract service KaleyraVideoService as explained here, in order to configure and connect the Kaleyra Video SDK after the notification payload has been intercepted to properly prompt incoming calls to the user or display new chat messages as android notifications.

• It is also possible to deactivate the automatic push notification handling strategy by settings the relative option as follows:

KaleyraVideo.pushNotificationHandlingStrategy = PushNotificationHandlingStrategy.Manual
// or KaleyraVideo.pushNotificationHandlingStrategy = PushNotificationHandlingStrategy.Automatic as default behaviour

• If manual push notification handling strategy has been set, it is required to implement your client listener for notifications (FCM, Huawei PushKit, OneSignal or any others) depending on the notification framework you have decided to use.
• Then, once received the notification, after that the payload has been recognized as an incoming call or chat Kaleyra Video payload, you will need to connect the Kaleyra Video SDK as follows:

KaleyraVideo.connect("userId", accessTokenProvider = { requestDate: Date ->
   Result.success("token")
})

• The incoming call or new chat messages will be automatically retrieved by the SDK after that has been connected. If a call is incoming this will be prompted to the user as well as new chat messages will be shown in the notification area as android notifications.