Heartbeat Integration Instructions

Integration Instructions for Android

There are no additional integration instructions for Android. This feature is enabled by default.

Integration Instructions for iOS

For iOS, additional steps are needed to wake up the app periodically. Consider the following:

• Background Processing should be used for performing heavy computation tasks in background. This method doesn’t have a period associated with it and it is advised to use it only once a day.

Some developers have suggested that setting requiresExternalPower on the BGProcessingTaskRequest increases its chances of getting executed. See Apple Documentation.

• Background fetch can be scheduled to run after a given period of time. iOS has a very complex and strict logic for allowing apps to be woken up for background fetch. Apple has also suggested that the background fetch requests should only be created when the application is in the foreground. This solution is ideal for applications which are used at least a couple of times a day by their users.

• Silent push notifications are far more reliable in waking up the application. As they are silent and therefore do not demand the user’s attention, silent notifications are immune to push notifications permissions set by the user.

We recommend implementing a silent notification for their reliability. Upon receiving a silent push notification, iOS will call the application:didReceiveRemoteNotification:fetchCompletionHandler method. The customer application responds with theZendrive.logSDKHealth method.

Add the following delegate method to your UIApplicationDelegate implementation:

- (void)application:(UIApplication *)application
    didReceiveRemoteNotification:(NSDictionary *)userInfo
          fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
    …
    Zendrive.logSDKHealth(.silentPushNotification) { error in
        // handle error
    }
 
  completionHandler(UIBackgroundFetchResultNoData);
}

Refer to the latest documentation for this delegate method, to ensure that it doesn’t interfere with any other existing notification handling implementations. Note that iOS places a restriction on sending more than 2 to 3 such notifications every hour.

Register the Client for Push Notifications

The client needs to register for push notifications and send its device token to the server. The application should have push notification capability enabled along with Remote Notifications background mode.

Fetch the Device Token

The application needs to register for remote notification and implement the delegate methods application:didRegisterForRemoteNotificationsWithDeviceToken and application:didFailToRegisterForRemoteNotificationsWithError.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
      [[UIApplication sharedApplication] registerForRemoteNotifications];
      return YES;
}
- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
     NSLog(@"registered for remote notifications");
    //Send this token to the server 
}
- (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
     NSLog(@"failed to register for remote notifications");
}

Convert token to hex string before sending to server

let deviceTokenString = deviceToken.map { String(format: "%02x", $0) }.joined()
NSLog("deviceToken string %@",deviceTokenString)

Generate a Push Notification on the Server

Generate a push notification certificate for the application. A push notification certificate can be generated through your Apple developer account:

• Export the push notification certification from keychain as a .p12 file.

• Convert this .p12 to a key.pem file.

  penssl pkcs12 -in pushServicesCert.p12 -out key.pem -nodes -clcerts

• Initialize an apns-client and send the notification. Make sure to set the apns-priority as delayed (i.e. value 5) and not send any alert badge or sound in the payload.

from apns2.client import APNsClient
from apns2.payload import Payload
from apns2.client import NotificationPriority

client = APNsClient('key.pem', use_sandbox=True, use_alternative_port=False)
def send_wakeup_push():
   token_hex = <token_hex_string>
   payload = Payload(content_available=1)
   topic = <bundle_identifier>
   client.send_notification(token_hex, payload, topic, priority=NotificationPriority.Delayed)