Using the On-Demand Services API to access collection and product details for AEM Mobile

Requirements

Prerequisite knowledge

Required products

  • Adobe AEM Mobile
  • Access to the On-Demand Services API

Introduction

This article will cover the usage of the AEM Mobile On-Demand Services API to retrieve product and collection information. This information can be used to provide data for Direct Entitlement servers to control content-authorization. AEM Mobile uses the same Direct Entitlement API as Digital Publishing Suite. This means that every Direct Entitlement Service implementation that is based on Direct Entitlement API v2 is compatible with AEM Mobile.

Setting up your project

To use the On-Demand Services API to access collection and product details, follow these steps.

  1. Download the On-Demand Services API document, and request an API key using the request form found inside the On-Demand Services API .zip file.

  2. Download the On-Demand Services SDK. This SDK will have a reference implementation that will rebuild a DPS issueList based on AEM Mobile.

  3. Set up a project in AEM Mobile, publish multiple collections, and use the Products & Subscriptions section of the On-Demand Portal (https://aemmobile.adobe.com) to configure multiple collections as retail (turn off "Free Product"). For details, see In-app purchases and subscriptions for AEM Mobile apps.

  4. Create a new Adobe ID. Example: de_user@company.com

  5. Add the Adobe ID ‘de_user@company.com’ to the projects that will retrieve the data. For that user, grant only the permissions to ‘View Article & Collection information’ and ‘View Product information’. For details, see Account administration for AEM Mobile.

  6. Generate a device_id and device_token using the Auth Exchange Tool. Please make sure that the Adobe ID used in this process are the ones (maximum of 3) that were specified in the API Key request form.

    The AEX token generator accepts only Adobe IDs, not Enterprise or Federated IDs. Therefore, you can use only Adobe IDs with the SDK.

  7. Modify ‘aemmobilesdk/configuration/credentials.php’ and update the variable to reflect your setup.

  8. Get the project Id for your project. This can be done in two ways.

    Method 1: Copying the project ID from the Portal

    Navigate to the Contents & Layouts section of the on-demand portal. Select a project from the dropdown list in the navigation bar. Select the URL in the browser.

    The project ID is listed after the text '/publication/'. In this sample URL, the project ID is in bold:

    https://aemmobile.adobe.com/content/index.html#/publication/bf8a2101-abe5-4a4b-a02e-f7d4f5502d3c/content

    Method 2: Using the On-Demand Services API

    Run recipe: recipe/authentication/getUserPermissions.php

    The following paths in the JSON response data could contain multiple project IDs: $data['masters'][#]['publications'][#]['id'];

    For example, the example project ID bf8a2101-abe5-4a4b-a02e-f7d4f5502d3c is found in $data['masters'][0]['publications'][2]['id']

Creating the recipe

To generate the issue list, you will need a list of Product IDs and Collections. There are recipes provided to generate the issue list using the AEM Mobile SDK:

  • In XML feed: `recipes/product/genIssueList.php`
  • In JSON: `recipes/product/genIssueListJson.php`

Setup

In this step, you will set the project ID, request the access token, and store it (in PHP session). The latter can be changed to store in a local database. The access token is valid for 48 hours.

$currentDir = dirname(__FILE__); 
$parentDir = dirname($currentDir); 
$grandParentDir = dirname($parentDir); 
// include the AEM Mobile On-Demand Services SDK
require_once($grandParentDir . '/aemmobilesdk/vendor/autoload.php');
use aemmobilesdk\contentService\Collection; 
use aemmobilesdk\productService\Product; 
use aemmobilesdk\userService\User;
// provide the publication GUID 
$strPublicationGuid = '';
// initialize the user object 
$objPublishUser = new User(); 
// set the publication GUID $objPublishUser->setPublicationGuid($strPublicationGuid); 
// request and store the access token
$objPublishUser->requestToken()->storeToken();

Database version: Instead of calling `storeToken()` at the end of the above example, you can use `getToken()` to get the access token directly and store it in the database. If you use this method, update aemmobile\userService\Authorization::getStoredToken() with the appropriate functionality to pull the access token from the database.

Best Practice: Always store the access token (default is via PHP session) and reuse it until it expired. Once expired, the SDK will automatically recall aemmobilesdk\authenticationService\ Authentication::requestToken().

List of product IDs

In this step, we will request for a list of product IDs and store it (in PHP session). The latter can be changed to store in a local database.

Best Practice: Make this step a standalone script; create a cron job that will call this standalone script to get and store the list of product IDs within a reasonable timeframe. This will depend on how often you will be updating the product IDs (for example, 15 minutes). See `recipes/product/storeProductList.php` for an example standalone script.

// initialize product object 
$objPublishProduct = new Product($objPublishUser); 
// request and store the list of product IDs WRT the account
$objPublishProduct->requestList()->storeList();

List of collections

In this step, we will request for a list of collections and store it in the variable `$arrResponseMessage`.

// initialize collection object 
$objPublishCollection = new Collection($objPublishUser); 
// get list of collections WRT the account 
$arrResponseMessage =
$objPublishCollection->requestList()->getResponse();

The `$arrResponseMessage` will contain an array of collection entity names. You will need to make a request per collection entity name to get its metadata, followed by another request to get its publishing status.

// iterate the list of collection entity names 
foreach ($arrResponseMessage as $collection) {
  // set the collection entity name
  $objPublishCollection->setIdFromHref($collection['href']);
  // get the collection metadata
  $arrCollectionData =
  $objPublishCollection->requestMetadata()->getResponse();
  // get the collection publishing status
  $bolPublishStatus =
  $objPublishCollection->requestStatus()->getPublishStatus();
}

At this point, you can iterate through the collection metadata and pull all or only the necessary metadata. Store the data either in XML or JSON, the latter would be preferable as it is faster.

foreach ($arrCollectionData as $strAttribute => $arrValue) {
   switch ($strAttribute) {
     case 'entityName':
       // store the entityName
       break;
     case 'department':
       // store the departments
       break;
     ... // add as many case as necessary
     default:
       // either store value as is or not at all
       break;
  }
}

Downloading the images

During the previous step, while iterating through the collection metadata, the script will download the images if and only if the collection entity has a background and/or thumbnail image and it is not already downloaded locally to the script. The latter part of the condition is to make the load time faster.

Best practice: Similar to how the product IDs are handled, the image downloads should be a standalone script, with a cron job to download the latest images within a reasonable timeframe. Please see 'recipes/product/downloadImages.php' for an example standalone script.

foreach ($arrCollectionData as $strAttribute => $arrValue) {
  switch ($strAttribute) {
    case '_links': // collection links
      foreach ($arrValue as $strInnerAttr => $arrInnerValue) {
        switch ($strInnerAttr) {
          case 'thumbnail':
          case 'background':
            // the image link is located in:
            // $strInnerValue['href']
            // i.e. contents/images/background
            // you can request the image by replacing "contents" with
            // the collection entity content URL and making a HTTP GET request
            break;
        }
      }
      break;
  }
}

Deployment in production

To access multiple projects, you can assign the same Adobe ID that you created above (de_user@company.com) to any other project.

If you are running a hosted entitlement server for multiple customers, you can follow the same recipe. You would ask your customers to add the Adobe ID (de_user@company.com) to their projects so your hosted entitlement server can access the data from the customer.

If the Adobe ID is removed from the project or the permissions to ‘View Articles & Collection’ and ‘View Product information’ are revoked, the information will not be accessible anymore.

Change log

2016/01/06

  • A "Downloading the images" section was added to "Creating the recipe."

Tato práce podléhá licenci Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported License.  Na příspěvky ze služeb Twitter™ a Facebook se nevztahují podmínky licence Creative Commons.

Právní upozornění   |   Zásady ochrany osobních údajů online