Edit in GitHubLog an issue

Fetching Recommendations with the Delivery API

The Adobe Target and Adobe Target Recommendations APIs can be used to deliver responses to web pages, but can also be used in non-HTML based experiences including apps, screens, consoles, emails, kiosks and other display devices. In other words, when Target libraries and JavaScript cannot be used, the Target Delivery API still allows us to access the full range of Target functionality to deliver personalized experiences.

To retrieve recommendations, send an Adobe Target Delivery API POST call with the appropriate contextual information, which may include a user ID (for use with profile-specific recommendations such as the user's recently viewed items), relevant mbox name, mbox parameters, profile parameters, or other attributes. The response will include recommended entity.ids (and may include other entity data) in JSON or HTML format, which can then be displayed in the device.

The Delivery API for Adobe Target exposes all existing features that a standard Target request provides.

The Delivery API:

  • Enables you to retrieve experiences or offers for a location and an audience in a RESTful manner.
  • Requires no authentication.
  • Only POSTs.
  • Does not process cookies or redirect calls.
  • Does not require or recognize "user roles." It simply fetches content or reports events to Target edge servers.

To use the Delivery API to deliver Target experiences—including recommendations—follow these steps:

  1. Create a Target activity (A/B, XT, AP, or Recommendations) using the Form-Based Composer (not the Visual Experience Composer).
  2. Use the Delivery API to get a response for the requests generated by the Target activity you just created.

Create a Recommendation using the Form-based Experience Composer#

To create recommendations that can be used with the Delivery API, use the Form-based Composer.

  1. First, create and save a JSON-based design to use in your recommendation. For sample JSON, plus background information regarding how JSON responses can be returned when configuring a form-based activity, see the documentation on Creating Recommendation Designs. In this example, the design is named Simple JSON. server-side-create-recs-json-design.png

  2. In Target, navigate to Activities > Create Activity > Recommendations, then select Form.

    server-side-create-recs.png

  3. Select a Property, and click Next.

  4. Define the location where you would like users to receive the recommendation's response. The example below uses a location named api_charter. Select your JSON-based design, created earlier, named Simple JSON. server-side-create-recs-form.png

  5. Save and activate the recommendation. It will generate results. Once the results are ready, you can use the Delivery API to retrieve them.

Use the Delivery API#

The syntax for the Delivery API is:

POST https://{{CLIENT_CODE}}.tt.omtrdc.net/rest/v1/delivery

  1. Note the client code is required. As a reminder, your client code may be found in Adobe Target by navigating to Recommendations > Settings. Note the Client Code value in the Recommendation API Token section. client-code.png

  2. Once you have your client code, construct your Delivery API call. The example below begins with the Web Batched Mboxes Delivery API Call provided in the Delivery API Postman collection, making relevant modifications. For example:

    • the browser and address objects were removed from the Body, since they are not required for non-HTML use cases
    • api_charter is listed as the location name in this example
    • the entity.id is specified, since this recommendation is based on Content Similarity, which requires a current item key to be passed to Target. server-side-Delivery-API-call.png Remember to configure your query parameters correctly. For example, be sure to specify {{CLIENT_CODE}} as necessary. <!--- Q: In the updated call syntax, entity.id is listed as a profileParameter instead of an mboxParameter as in older versions. ---> <!--- Q: Old image server-side-create-recs-post.png Old accompanying text: "Note this recommendation is based on Content Similar products based on the entity.id sent via mboxParameters." ---> client-code3
  3. Send the request. This executes against the api_charter location, which has an active recommendation running on it, defined with your JSON design which will output a list of recommended entities.

  4. Receive a response based on the JSON design. server-side-create-recs-json-response2.png The response includes the key ID, as well as the entity IDs of the recommended entities.

    Using the Delivery API with Recommendations in this way enables you to perform additional steps prior to displaying recommendations to the visitor on the non-HTML device. For example, you can take the response from the Delivery API to perform an additional, real-time lookup of entity attribute details (inventory, price, rating, and so on) from another system (such as a CMS, PIM or ecommerce platform), before displaying final results.

    Using the approach outlined in this tutorial, you can get any application to leverage the response from Target to provide personalized recommendations!

Example Implementations#

The following resources provide examples of various non-HTML focused implementations. Keep in mind every implementation will be unique, due to the system and devices involved.

ResourceDetails
Consuming RESTful APIs in AEMHow to create and deploy an Adobe Experience Manager OSGi bundle that consumes data from a third-party RESTful web service.
Adobe Target Everywhere - Implement Server Side or in the IoTAdobe Summit 2019 Lab that provides hands-on experience for a React application that leverages Adobe Target server-side APIs.
Adobe Target in a Mobile App Without the Adobe SDKThis guide shows you how to set up Adobe Target in your mobile app without installing the Adobe SDK. This solution uses the Tealium SDK webview and the Remote Commands module to send and receive requests to the Adobe Visitor API (Experience Cloud) and the Adobe Target API.
How Adobe Target Works in Mobile AppsHow Target works with the Mobile SDK
Configuring the Target extension in Experience Platform Launch and Implementing Target APIsSteps for configuring the Target extension in Experience Platform Launch, adding the Target Extension to your app, and implementing Target APIs to request activities, prefetch offers, and Enter visual preview mode.
Adobe Target Node ClientOpen-sourced Target Node.js SDK v1.0
Server Side overviewInformation about Adobe Target Server Side Delivery APIs, Server Side Batch Delivery APIs, Node.js SDK, and Adobe Target Recommendations APIs.
Adobe Campaign Content Recommendations in EmailBlog that describes how to leverage content recommendations in email via Adobe Target and Adobe I/O Runtime in Adobe Campaign.

Managing Recommendations Setup with APIs#

Most of the time, recommendations are configured in the Adobe Target UI, then used or accessed via the Target APIs, for reasons such as the ones mentioned in the sections above. This UI-API coordination is common. However, sometimes users may want to perform all actions via APIs—both setup, as well as the use of results. Although much less common, users can absolutely configure, execute, and leverage the results of recommendations entirely using the APIs.

We learned in an earlier section how to manage Adobe Target Recommendations entities and deliver them server-side. Similarly, the Adobe Developer Console allows you to manage criteria, promotions, collections, and design templates without having to log in to Adobe Target. A complete list of all Recommendations APIs may be found here, but here is a summary for reference.

ResourceDetails
CollectionsList, create, get, edit, and delete collections.
CriteriaList and get criteria.
DesignsList, create, get, edit, delete, and validate designs.
EntitiesSave, delete, and get entities.
PromotionsList, create, get, edit, and delete promotions.
Category CriteriaList, create, get, edit, and delete category criteria.
Custom CriteriaList, create, get, edit, and delete custom criteria.
Item CriteriaList, create, get, edit, and delete item criteria.
Popularity CriteriaList, create, get, edit, and delete popularity criteria.
Profile Attribute CriteriaList, create, get, edit, and delete profile attribute criteria.
Recent CriteriaList, create, get, edit, and delete recent criteria.
Sequence CriteriaList, create, get, edit, and delete sequence criteria.

Reference documentation#

Summary and Review#

Congratulations! By finishing this tutorial, you have learned how to:

Was this helpful?
  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.