PushAuth™ SDK Setup

Let’s walk through the initial steps of setting up the SDK and registering the user’s push token with UnifyID.

Prerequisites

The PushAuth Android SDK requires:

  • Android API level 24 or greater
  • Java 7 or greater
  • Firebase
    This allows the SDK to use Firebase Cloud Messaging (FCM) to send push notifications. A complete guide to adding Firebase to your Android project can be found at firebase.google.com/docs/android/setup.

The PushAuth iOS SDK requires:

  • Swift 4.2 or greater
  • iOS 10.0 or greater

Additionally, we recommend that you install the iOS SDK via CocoaPods, a dependency manager for iOS projects. Please refer to CocoaPods Guides - Getting Started for more information.

Installation and Setup

Android

Gradle Dependencies and Repositories

UnifyID Android SDKs are deployed to the Maven Central Repository. To easily include PushAuth, first add mavenCentral() to your top-level build.gradle in both the buildscript and allprojects blocks, under repositories:

buildscript {
  repositories {
    mavenCentral()
  }
}

allprojects {
  repositories {
    mavenCentral()
  }
}

Then, add the following to the dependencies section in your module-level build.gradle file:

// The dependencies block in the module-level build configuration file
// specifies dependencies required to build only the module itself.
dependencies {
  implementation 'id.unify.sdk:sdk-core:1.1.0'
  implementation 'id.unify.sdk:sdk-pushauth:1.1.0'
}

For more information about the Android build system, please refer to Android Studio - Configure your build.

To download the Android SDK directly, find us on GitHub at github.com/UnifyID/unifyid-android-sdk.

App Permissions

Prior to using the SDK, you’ll also want to make sure the following permissions are present in the root manifest element of your AndroidManifest.xml file:

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

iOS

Once CocoaPods is set up, you’ll want to add the PushAuth SDK pod to your project:

  1. Add the following line to your Podfile:
    pod 'UnifyID/PushAuth'
    
  2. Install the pod:
    $ pod install
    
  3. Open your project using the workspace file.

To download the SDK directly, find us on GitHub at github.com/UnifyID/unifyid-ios-sdk and check Releases.

Integration

1. Initialize the SDK

Don’t have an SDK Key yet? Learn how to create your first project.

Android

Initialize an instance of the SDK in your activity’s onCreate() method:

// Initialize the SDK with a list of modules to use.
// Currently only PushAuth is available.
List modules = new ArrayList<>();
modules.add(new UnifyIDPushAuthModule());
UnifyID.initialize(getApplicationContext(), sdkKey, user, modules, new CompletionHandler() {
  @Override
  public void onCompletion() {
    // Initialization was successful
  }

  @Override
  public void onFailure(UnifyIDException e) { }
});

iOS

Initialize an instance of the SDK in your root object or app delegate:

import UnifyID

let unify : UnifyID = { try! UnifyID(
    sdkKey: "https://xxx@config.unify.id",
    user: "unique-immutable-user-identifier"
)}()

Once the SDK is initialized, you’ll access PushAuth functionality through its pushAuth instance:

import PushAuth
let pushAuth = unify.pushAuth

The sdkKey and user Parameters

The sdkKey resembles a URL and is found in the Settings section of the Developer Dashboard.

The user that you provide during SDK initialization should be a unique, immutable identifier for your user. It will be the same value that you use in the APIs to query the authentication status after a push has been sent. While this identifier is treated as an opaque string, we highly recommend that you choose a value that does not reveal any additional information about the user. This includes emails, phone numbers, or any other Personally Identifiable Information.

Please make sure that the user identifier is unique across all users and also does not change for a given user.

2. Enable Push and Request Permission (iOS only)

The PushAuth Android SDK does not have a separate step to enable and request user permissions for push notifications. Initializing the Android SDK is all that is required.

If you already have a published app that uses push notifications, you’re likely already familiar with this next step.

In order to use PushAuth, your app will need to have:

  1. Push notifications enabled
  2. Permission from each app/device you wish to push to

Here are a few resources we’ve found helpful in getting this set up:

3. Register the Device Token (iOS only)

The PushAuth Android SDK automatically registers the device token with UnifyID upon SDK initialization. No separate step is required.

Successfully completing step 2 above means that you now have a device token that permits you to send push notifications to your user’s device.

Share this token with UnifyID and associate it with this user, so that future PushAuth requests for this user will deliver notifications to this device:

pushAuth.registerPushToken(token) { ... }

4. Integrate FcmMsgListenerService (Android only)

In order for the PushAuth Android SDK to receive push notifications, you will need to allow the SDK’s FcmMsgListenerService to handle push notifications. There are two options depending on your setup.

Option 1

If your app does not have an existing notification handler, simply add the following lines to your AndroidManifest.xml file as a child of the <application> element. This allows FcmMsgListenerService to receive push notifications:

<service
  android:name="id.unify.sdk.pushauth.FcmMsgListenerService"
  android:exported="false">
    <intent-filter>
      <action android:name="com.google.firebase.MESSAGING_EVENT" />
    </intent-filter>
</service>

Option 2

If your app has an existing notification handler, no changes to your AndroidManifest.xml are needed. However, instead of having your handler extend FirebaseMessagingService, have it extend FcmMsgListenerService (which in turn extends FirebaseMessagingService).

Important: Make sure to call super in your override methods for onMessageReceived(RemoteMessage) and onNewToken(String).

// Your handler should extend FcmMsgListenerService
public class MyFcmService extends FcmMsgListenerService {
    @Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        // Required. This allows the PushAuth SDK to receive messages.
        super.onMessageReceived(remoteMessage);

        // my code below here
    }

    @Override
    public void onNewToken(String token) {
        // Required. This provides UnifyID with the device token.
        super.onNewToken(token);

        // my code below here
    }
}

Next Steps

Before you can send your first push, you’ll need to provide us with credentials to send push notifications:

  • For Android, an FCM/GCM server key
  • For iOS, an Apple Push Notification service (APNs) certificate

Supply Push Credentials

Updated: