Developer Chat Apache 2.0 License Objective-C/Swift Web Support


Ongoing Postbox

Introduction

An Ongoing Postbox allows your app to push data to the user over multiple app sessions without the use of digi.me app after initial consent has been given*.

From developer perspective the authorization process is almost identical to regular authorization. Under the hood we use OAuth 2.0 with JWT and JWS with RSA signing and verification to issue a medium lived, refreshable OAuth token, which is used to re-query user’s data without the need to leave your app.

Here is a simplified sequence diagram of how the OAuth flow is implemented:

The SDK handles all of this for you.

Ongoing Access is for you if:

  • You need to regularly push data to your user
  • You are using an ongoing push contract

* refreshTokens used to refresh accessTokens do eventually expire (for example - 30 days). When this happens, user will need to be directed back to digi.me app for re-authorization.

Example

Please refer to our Ongoing Postbox example in the Swift Example App for more details on data and metadata.

How to use

Create Ongoing Postbox

Simply use the new authorizeOngoingPostbox method on an instance of DMEPushClient:

Objective-c
[pushClient authorizeOngoingPostboxWithExistingPostbox:nil completion:^(DMEOngoingPostbox * _Nullable postbox, NSError * _Nullable error) {
    // You may now push data to the postbox
}];
Swift
pushClient.authorizeOngoingPostbox(withExisting: nil, completion: { postbox, error in
    // You may now push data to the postbox
})

You may notice that upon completion of this method, the SDK supplies a DMEOngoingPostbox which contains the postbox identifier and an OAuth token. This is key to restoring access to the Ongoing Postbox and we recommend you store this - you will need it later.

Our recommendation would be to save it to keychain.

Refreshing Ongoing Postbox

If you have previously obtained user’s consent, and are in possession of a DMEOngoingPostbox, you can push data to your users without them having to leave your app.

To do this, simply call the following method on a new DMEPushClient instance:

Objective-c
[pushClient authorizeOngoingPostboxWithExistingPostbox: myOngoingPostbox completion:^(DMEOngoingPostbox * _Nullable postbox, NSError * _Nullable error) {
    // You may now push data to the postbox
}];
Swift
pushClient.authorizeOngoingPostbox(withExisting: myOngoingPostbox, completion: { postbox, error in
    // You may now push data to the postbox
})

It is important to replace your existing Ongoing Postbox with the one returned in the completion block as this may contain an updated session key which will be required to push data.

Push Data to Ongoing Postbox

There is a new function in DMEPushClient dedicated to pushing to an Ongoing Postbox:

Objective-c
[pushClient pushDataToOngoingPostbox:myOngoingPostbox metdata:myMetadata data:myData completion :^(DMEOngoingPostbox * _Nullable postbox, NSError * _Nullable error) {
    // Handle error or store updated Ongoing Postbox
}];
Swift
pushData(to: myOngoingPostbox, metadata: myMetadata, data: myData, completion: { updatedPostbox, error in
    // Handle error or store updated Ongoing Postbox
})

It is important to replace your existing Ongoing Postbox with the one returned in the completion block as it may contain an updated OAuth token.

This is because the SDK will try to automatically refresh an accessToken using a refreshToken, if necessary, (both of these contained in DMEOAuthToken in the DMEOngoingPostbox), generating a new DMEOAuthToken.

Configuration Options

There is a new property available on DMEPushConfiguration object - autoRecoverExpiredCredentials. This defaults to true, which means that if the refreshToken contained in DMEOAuthToken has expired, the user will be directed to the digi.me app, so that this can be regenerated.

If you wish to direct the user back to digi.me app manually, set this property to:

Objective-c
configuration.autoRecoverExpiredCredentials = NO;
Swift
configuration.autoRecoverExpiredCredentials = false;

When set to false, the SDK will return an AuthErrorOAuthTokenExpired error in completion.

Anything else?

If you need help setting up the rest of the flow, or simply more detail, then head on over to Getting Started.