PushAuth™ SDK Setup

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


The PushAuth Android SDK requires:

  • Java 7 or greater
  • Android API level 24 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 5.1 or greater
  • iOS 10.0 or greater
  • CocoaPods 1.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


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 {

allprojects {
  repositories {

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-pushauth:1.7.6'

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 and Auto Backup Settings

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" />

Also, if Android Auto Backup is enabled in your project, you’ll want to add tools:replace="allowBackup" under <application ...> of your AndroidManifest.xml:

<manifest ... >
        <!-- Add following line -->
<manifest ... >

Managing App Size

In order to keep your app as small as possible we recommend that you enable code and resource shrinking for your release build. To do so, add the following to your module-level build.gradle file. You can read more about these optimizations here.

android {
    buildTypes {
        release {
            minifyEnabled true
            shrinkResources true
            proguardFiles getDefaultProguardFile(


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

  1. Add the PushAuth SDK dependency to your Podfile:
     pod 'UnifyID/PushAuth'
  2. Add a post install hook to ensure all dependent projects are built with library evolution support:
     # Enable library evolution support on all dependent projects.
     post_install do |pi|
         pi.pods_project.targets.each do |t|
             t.build_configurations.each do |config|
                 config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
  3. Install the pod:
     $ pod install
  4. 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.


1. Initialize the SDK

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


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

UnifyID.initialize(getApplicationContext(), sdkKey, user, new CompletionHandler() {
    public void onCompletion(UnifyIDConfig config) {
        PushAuth.initialize(getApplicationContext(), config);

    public void onFailure(UnifyIDException e) {
        // Initialization failed


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

import UnifyID

let unifyid : 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 = unifyid.pushAuth

The sdkKey and user Parameters

The sdkKey resembles a URL and is found in the Settings section of the UnifyID 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.

If you would like to require trusted device registration, you must also provide a string value for the optional challenge parameter. For more information, see this page.

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:

      <action android:name="com.google.firebase.MESSAGING_EVENT" />

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 {
    public void onMessageReceived(RemoteMessage remoteMessage) {
        // Required. This allows the PushAuth SDK to receive messages.

        // my code below here

    public void onNewToken(String token) {
        // Required. This provides UnifyID with the device 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