Your First PushAuth™ Session
UnifyID PushAuth notifications originate through an API call from your backend server, and generally follow a common lifecycle:
- Push notification session is created via PushAuth API.
- Notifications are received on the user’s registered devices.
- The SDK responds to the PushAuth session based on the user’s response.
- 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
}
}
}
Identify PushAuth notifications from your own
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 (iOS only)
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 (ie, unresponded to) notifications that have not expired. Refer to the PushAuth iOS 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.