How to use DPS Entitlement Service

The DPS Entitlement Service is designed to allow users to test direct entitlement and restricted distribution in development apps. It is intended for demos, proofs of concept (POCs), and testing. It should not be used for production.

Restricted distribution is one form of entitlement in which users must be explicitly entitled to a folio to view it. For restricted distribution, you must set your folio as “retail” without an accompanying price in the respective marketplace.

This service is limited to 1000 HTTP requests per day from a viewer, based on App ID. Requests from the admin are not limited. If you would like to increase the request limit or remove it, contact Derek Lu, delu at adobe.

This service is composed of two pieces: an admin and XML services. The admin allows you to create users and groups and entitle folios to them. The XML services implement the three XML APIs that third party entitlement requires.

For more information about entitlement visit the direct entitlement section on Adobe Developer Connection.

If you would like to customize a storefront visit the configurator.

Login

1. Go to https://dpsapps.adobe.com/entitlement_admin/.
2. Login with an Adobe ID that has the application role enabled.

Values for App Builder

Your test app will use the Service URL and Integrator ID from the Entitlement Admin. These values are used in DPS App Builder in the Entitlement Details pane.

1. From the Entitlement Admin, copy the Service URL value, https://dpsapps.adobe.com/entitlement_admin/services/index.php. In App Builder, go to the Entitlement Details pane and enter the value in the Service URL and Service Auth URL input fields for iOS apps. For Android and Windows apps, the Service URL value is not required.
2. From the Entitlement Admin, copy the Integrator ID (dps_entitlement_poc) and enter it in App Builder for the Integrator ID.

Enter App ID

1. In the Entitlement Admin, enter your App ID in the App ID input. This should match the App ID from your mobileprovision file. You can view the App ID for your completed viewer from the home screen of App Builder.

2. When you create your viewer in App Builder you must select the “Send app ID and version” checkbox, this is found in the Entitlement Details pane of DPS App Builder.

Managing Users

Using the Entitlement Admin you can create and update users. Users must have a username and password and contain an optional description field. A user can be entitled to one or more folios and can be assigned to one or more groups.

For example, suppose you are creating a Sales app and you have three users: Cheryl, Maria, and Clarence and you publish a retail folio specific to each user. In addition, you create multiple groups called North, South, and West. Each group is then entitled to a folio specific to their region such as “North Sales Policies”. In this example, Cheryl has been entitled to a folio named “Cheryl” and has been added to the “North” group. When she logs in she will see the folio named “Cheryl” and “North Sales Policies” since she is in the “North” group.

1. To add a user click “Add User” from the “Users” tab.
2. To edit a user, select a user from the grid then either click “Edit User “or double-click on a user entry.
3. In the Edit User dialog, you can update the username, password or description. You only need to set the password if you are updating it, otherwise you can leave it blank.
4. To entitle a folio to the user, select a folio from the first drop down and click the “+” button.
5. To add the user to a group, select a group from the second drop down and click the “+” button.
6. To remove a folio or group from the user, select it from the list and click “Remove”.

Managing Groups

Using the Entitlement Admin you can create and update groups. Groups must have a name and contain an optional description field. You can entitle folios to a group and assign users to a group. Groups are not required although they are helpful for entitling groups of users.

1. To add a group click “Add Group” from the “Groups” tab.
2. To edit a group, select a group from the grid then either click “Edit Group” or double-click.
3. In the Edit Group dialog, you can update the name or description.
4. To entitle a folio to the group, select a folio from the first drop down and click the “+” button.
5. To add a user to the group, select a user from the second drop down and click the “+” button.
6. To remove a folio or user from the group, select it from the list and click “Remove”.

Managing Folios

The list of folios shows the folios available based on the DPS account used to login to this service. Only published and public folios are shown. Unpublished or Private folios are not available for entitlement. Both free and retail folios will be displayed, but entitlement only applies to retail folios, including folios intended for restricted distribution. Folio metadata cannot be edited from this tool.

1. To assign a folio to groups or users, select a folio from the grid then either click “Edit Folio” or double-click.
2. In the Edit Folio dialog, to entitle a group to the folio, select a group from the first drop down and click the “+” button.
3. To add a user to the group, select a user from the second drop down and click the “+” button.
4. To remove a group or user from the folio, select it from the list and click “Remove”.

When your folios are entitled, you are ready to test on the device.

Make sure that you publish restricted folios as Public and Retail. (Private folios do not appear in your app, and Free folios are available to all users.)

When using DPS App Builder to build your iOS app, make sure that you do the following:

• For App Type, choose Multi Folio with Entitlement.
• In the Entitlement Details pane, specify the “Service URL,” “Service Auth URL,” and “Integrator ID” values as described earlier in the “Values for App Builder” section. You must also specify a Forgot Password URL (it can be any URL for testing purposes), and select “Send App ID and Version.”
• In the Navigation Toolbar pane, select “Hide Buy Buttons” so that retail folios do not appear in the library unless users are entitled to them.

For information on creating a DPS viewer, read the DPS App Builder overview.

Once you have your viewer running on your device, you can test 3^rd party entitlement by tapping the sign in button and signing in. Once you have successfully logged in, you should see the retail folios entitled for the user.

Troubleshooting

1. If you are unable to sign in, verify that you are entering a valid username/password.
2. Verify that you have entered the correct integrator ID in App Builder.
3. Verify that Send app ID and version is checked in App Builder.
4. Verify that the correct App ID is entered in the admin.

By using the DPS Entitlement Service you can test 3^rd party entitlement and restricted distribution. 

For more information about entitlement visit the direct entitlement section on devnet. If you would like to customize a storefront visit the configurator.

If you would like to download and install this entitlement service on your own server go to How to install the DPS Entitlement Server.

Comments are currently closed as we migrate to a new commenting system. In the interim, please provide any feedback using our feedback form. Thank you for your patience.