Your First PushAuth™ Session

UnifyID PushAuth notifications originate through an API call from your backend server, and generally follow a common lifecycle:

  1. Push notification session is created via PushAuth API.
  2. Notifications are received on the user’s registered devices.
  3. The SDK responds to the PushAuth session based on the user’s response.
  4. Your backend server queries the API for the PushAuth’s status.

Create a PushAuth Session

Each time you wish to authenticate a user using PushAuth, you’ll initiate a new PushAuth session through the API. The concept of a “session” exists because a single authentication attempt can send push notifications to multiple devices that are registered to the user.

While the SDK Key you used previously works with the SDK, a separate, private API Key is needed for the API. Learn more about using the API and making authenticated calls.

Create a PushAuth session with a POST to the /v1/push/sessions API endpoint:

$ curl https://api.unify.id/v1/push/sessions \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $SERVER_API_KEY" \
  --request POST \
  --data '{"user":"user-identifier","notification":{"title":"PushAuth Test","body":"Hello, World!"}}'

A successful call will return a PushAuthenticationSession object:

{
  "id": "...",
  "status": "sent",
  "notificationCount": 2,
  "detail": null,
  "expiresAt": "...",
  "updatedAt": "..."
}

Receive Notifications in the SDK

Android

If the Android SDK has been integrated correctly, PushAuth notifications will automatically be displayed to the user and they will be able to accept or reject the request. No additional code or handling is necessary.

iOS

In most cases, the user will see a notification displayed on their home screen with the option to “Accept” or “Reject” the request. They may also simply tap on the notification to launch your app. In all three cases, Apple will wake up your app and call userNotificationCenter(_:didReceive:withCompletionHandler:) on your app’s UNUserNotificationCenterDelegate as a UNNotificationResponse` object.

Use pushAuthRequest to obtain a PushAuthRequest object to determine the user’s action:

func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void) {
  if let pushAuthRequest = pushAuth.pushAuthRequest(response) {
    switch pushAuthRequest.userResponse {
    case .accept, .decline: // User responded from notification
      // Skip presenting if you like, and send user response direct
    case .unknown:
      // User tapped main body and did not make a response, present request
    }
  }
}

Distinguish PushAuth notifications from other notifications
Because your app may handle non-PushAuth notifications as well, use the pushAuthRequest method to attempt to retrieve a PushAuthRequest object. If the notification did not come from UnifyID, nil will be returned and you can handle it accordingly.

Alternatively, if your app is already in the foreground, Apple will instead call userNotificationCenter(_:willPresent:withCompletionHandler:) on UNUserNotificationCenterDelegate as a UNNotification object, allowing you to handle displaying the notification:

func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
  if let pushAuthRequest = pushAuth.pushAuthRequest(notification) {
    // No user response will be available, present to user
  }
}

Retrieve Pending Notifications

If for any reason the push notification was not received by the device or responded to, your app can call the getPendingAuthenticationRequests to fetch any pending (i.e., unresponded to) notifications that have not expired. Refer to the PushAuth iOS SDK reference and PushAuth Android SDK reference for additional information.

Presenting Notifications

Android

The PushAuth Android SDK provides a default view for notifications, but if you’d like to customize the display, you can use the PushAuthUIHandler.setCustomPushAuthUI method to customize the builder. This code can be run prior to SDK initialization or onCompletion:

PushAuthUIHandler.setCustomPushAuthUI(new OnNotificationCreate() {
    @Override
    public NotificationCompat.Builder getCustomNotificationUI(PushAuthUIPayload payload) {
        return new NotificationCompat.Builder(context, "my_channel_id")
            .setSmallIcon(R.drawable.my_notification_icon) // set notification icon
            .setContentTitle(payload.getTitle()) // set notification title
            .setContentText(payload.getBody()); // set notification body
    }
});

iOS

When the user taps the notification without choosing a response (and launches the app), or when you retrive a pending notification, you’ll need to present the PushAuth request to the user. Many apps may want to present the PushAuth request in a custom UI, but if instead you’d like a native alert to be presented and have the result automatically sent to UnifyID, use the convenience method presentAsAlert and pass in the view controller:

pushAuthRequest.presentAsAlert(vc) { result
  // Result is an error, or the result that user selected and was sent to server
}

Responding to a PushAuth Request

Android

When a user accepts or rejects a PushAuth notification, the response is automatically sent to UnifyID.

iOS

Unless you use the presentAsAlert method discussed above, the user’s response to the PushAuth request is not automatically reported back to UnifyID. Instead, responding to the request is a separate action.

If the user directly accepted or rejected the request from the notification, you can send this result to UnifyID with the respond method:

pushAuthRequest.respond(pushAuthRequest.userResponse)

If you separately presented the request to the user and received their response, you can call respond by using the DirectResponse class:

pushAuthRequest.respond(DirectResponse.accept("Optional detail string"))
// or
pushAuthRequest.respond(DirectResponse.reject())

The detail string is optional and will be returned by subsequent API calls.

Get the Status of a PushAuth Session

From your backend, you’ll want to poll the PushAuth API to check on the status of this session:

$ curl https://api.unify.id/v1/push/sessions/{id} \
  --header "Content-Type: application/json" \
  --header "X-API-Key: $SERVER_API_KEY"

The same PushAuthenticationSession object will be returned:

{
  "id": "...",
  "status": "accepted",
  "notificationCount": 2,
  "detail": "Option detail string",
  "expiresAt": "...",
  "updatedAt": "..."
}

The status will indicate the current status (eg, sent, accepted, rejected). While the status is still sent, you should continue requesting the status for some time.

PushAuth sessions will naturally expire based on the secondsToExpire parameter used during creation, but if you’d like to cancel it early, you can update a PushAuth session’s status with canceled via the API. Refer to the PushAuth API reference for additional information.

Updated: