Keep data up to date¶

A local cached Mobile Key is a short-life cryptographic key, which allows the app to unlock a specific lock. When a valid Mobile Key is cached, the lock can also be unlocked when the smartphone has no network connection.

The Tapkey Mobile SDK for Android offers multiple strategies to keep data up to date. For best results, they should be combined.

Regular polling¶

Tapkey provides an Android BroadcastReceiver that automatically caches such data frequently in the background. To enable this feature, PollingScheduler.register() has to be called in Application.onCreate().

public class App extends Application implements TapkeyAppContext{

    @Override
    public void onCreate() {
        super.onCreate();

        …

        /*
         * Register polling scheduler.
         * The PollingScheduler polls for notifications from the Tapkey Trust Service. Note that
         * the job ID must be unique across the app. The default interval is 8 hours.
         */
        PollingScheduler.register(this, 1, PollingScheduler.DEFAULT_INTERVAL);
     }
}

Using the SDK's PollingScheduler class requires the android.permission.RECEIVE_BOOT_COMPLETED permission. Otherwise, background polling won't work after the device reboots.

<manifest … >
    …
    <uses-permission android:name="android.permission.RECEIVE_BOOT_COMPLETED"/>
    <application … >
    …
</manifest>

Manual polling¶

While the PollingScheduler is periodically looking for updated keys, it is recommended to poll for updates whenever updates are expected. NotificationManager#pollForNotificationsAsync() can be used to manually check for updates. Manually checking for updated keys is recommended in the following situations:

• After a user has been logged in to the SDK.
• After a new grant has been issued for a logged-in user.
• After a grant that affects the current user has been modified or revoked.
• After grants, affecting locks that one of the logged-in users has access to, have been revoked. The logged-in users might receive updated revocation information.

Push Notifications¶

With push notifications, Tapkey will notify clients when Mobile Keys have been created, changed, or revoked. The Tapkey Mobile SDK for Android will automatically download or delete the Mobile Keys.

Preparations¶

1. Setup Firebase Project

   Follow the Firebase Documentation to create a Firebase project and to set up the Android project.

2. Connect Tapkey with Firebase

   Follow these steps to register a Mobile App and configure Push Notifications

Default Implementation¶

The Tapkey Mobile SDK for Android provides a default implementation for Android, which is easy to integrate. This implementation is perfect for apps, which do not use Firebase Cloud Messaging for their own purposes.

Add the Tapkey.Fcm module to the dependencies in the gradle.build file of the target application:

dependencies {
    implementation 'com.tapkey.android:Tapkey.MobileLib:x.x.x.x'
    implementation 'com.tapkey.android:Tapkey.Fcm:x.x.x.x'
}

Register the provided PushNotificationTokenProvider to the TapkeyServiceFactoryBuilder:

TapkeyServiceFactory sf = new TapkeyServiceFactoryBuilder(this)
    .setPushNotificationProvide(FirebasePushNotificationTokenProvider.Instance)
    .build()

That's all, the Tapkey Mobile SDK for Android will now use the configured Firebase Cloud Messaging for receiving Push Notifications.

Custom Implementation¶

If the target app is using already Firebase Cloud Messaging for its own purposes, it will be required to provide a custom implementation.

Create PushNotificationTokenProvider¶

Tapkey Mobile SDK for Android requires a PushNotificationTokenProvider to be able to register for Push Notifications. Create a custom implementation, which fits the requirements of the target application.

public class CustomPushNotificiationProviderImpl implements PushNotificationTokenProvider {

    @Override
    public Promise<String> registerForPushNotificationsAsync() {
        // ToDo: register for Push Notification and return the registration token
    }
}

Register the custom implementation to the TapkeyServiceFactoryBuilder:

TapkeyServiceFactory sf = new TapkeyServiceFactoryBuilder(this)
    .setPushNotificationProvide(new CustomPushNotificiationProviderImpl())
    .build();

Forward Push Notifications¶

When your app receives a Push Notification that is intended for the Tapkey Mobile SDK for Android, it has to be forwarded.

Either forward all Notifications. Tapkey Mobile SDK for Android will ignore Push Notifications, which are not intended for the Tapkey Mobile SDK for Android. PushNotificationManager.receivedPushNotification(data) will return if it was intended for Tapkey Mobile SDK for Android or not.

Map<String, String> data = remoteMessage.getData();

tapkeyServiceFactory.getPushNotificationManager()
    .receivedPushNotification(data)
    .continueOnUi(handled -> {

        if(handled) {
            // was handled by tapkey
            return null;
        }

        // Handle push notification

        return null;
    })
    .conclude();

Or check if the Notification is intended for Tapkey Mobile SDK for Android before forwarding it:

Map<String, String> data = remoteMessage.getData();

if (data.containsKey(PushNotificationManager.TAPKEY_PUSH_NOTIFICATION_IDENTIFIER)) {
    tapkeyServiceFactory.getPushNotificationManager()
        .receivedPushNotification(data)
        .conclude();
}

Update Registration Token¶

When the Push Notification Registration Token has been changed, the new token must be forwarded to the Tapkey Mobile SDK for Android:

getPushNotificationManager()
    .updateRegistrationToken(token)
    .conclude();