The test form in distribution is used to test authentication API calls from your web browser, mimicking the exact same calls the app will use to sign in and access content, but displaying more troubleshooting information.

In the form you have several input fields, the first one (or two) will be the user input parameters, where you will need to enter in the user details as you would normally in the app.

UUID - This is a unique ID for your mobile device, for the vast majority of purposes in the test form, this can be left as our placeholder default

Force Token - Is used to test the API using an previously generated token, rather than calling the Sign In method again

Product ID - This is a selected product ID which is used to test the Edition Credentials method response, as in the app Edition Credentials is called in reference to a particular product

Endpoint - Some authentication providers, such as ABS, will need to reference live product IDs for the authentication calls. This Endpoint selection allows you to use an endpoint other than the main content feed, such as a development or staging endpoint.

Responses

Sign In

The nature of the sign-in method is to check that your Third-Party Authentication API recognises the user details entered into the sign-in form in the app.

The response from a successful sign-in method will be a user token which the app will store for use in the Verify Subscription and Edition Credentials methods. This means we have successfully contacted the Third-Party API and they have confirmed the user details to be correct.

Or the response will be 'Not Recognised', which means that we've successfully contacted your Third-Party API - but they did not recognise the user's log-in details. This will usually mean the details entered are not correct, or the Third-Party is not returning the correct state for the user.

Verify Subscription

This method is called when a user initially signs in, as well as every time the app is opened. The purpose of this call is to check if the user has a valid subscription for the app and return which products they have access to under that subscription.

If we were successful in contacting your Third-Party Authentication API, and the API has confirm that the token generated in the 'Sign In' method is correctly linked to an active subscription then you'll see the <subscription> state attribute will be 'Active'.

Additionally, there may be custom attributes listed in the <userInfo> tag, which can feed back to the app for custom analytics purposes.

Additionally here, we may return a list of Product IDs that the user is entitled to - this mean that the authentication is 'Issue-Based' and the user only has access to certain editions, otherwise it will be 'Access-Based' and the user will receive access to everything if they have a valid subscription.

If the Third-Party API server has responded that the user does not have an active subscription, or does not have a valid subscription for the app then you will see <subscription> state listed as 'inactive'. This will either mean that there is not an active valid subscription on the user's account, or that the Third-Party Authentication API is not returning the correct state for that user.

DUTA

In addition, it shows the DUTA status of all the user info elements:

We may add addition information in the comments of the xml: '<!-- Comments here -->'

This will sometimes include useful troubleshooting information such as the exact response from the origin Third-Party API server.

Edition Credentials

In the app, this method is used when a user attempts to download an edition - usually in the backend we run a similar check with your Third-Party Auth API to verify the subscription on their account and confirm it is valid for the edition/product requested.

If this has been successful and the user is entitled to the edition we will return credentials for the edition which consists of a <userid> and <password> token.

However if after contacting your Third-Party API, we do not get back a valid subscription for the product requested then we will return <error> status 'Not Entitled'. This will either mean that there is no valid subscription on the user's account, or your Third-Party API is not returning the correct value for this user.