Adobe  I/O

Adobe Target

Delivery

Adobe Target lets your application make mbox calls from any browser, mobile device, or even another server.  The Server Side delivery API is specifically designed to integrate Adobe Target with any server side platform that makes HTTP/s calls.  You can use the API to integrate your custom application with Target.  This is especially valuable for organizations that want to deliver targeting to a non-browser based, IoT device such as a connected TV, kiosk, or
in-store digital screen.  This API implements existing mbox features in a RESTful manner.  This API does not process cookies or redirect calls.

Authentication and Authorization

There is no authentication for this API.  

There is no notion of a "user role" in the Server Side Delivery API because it represents a call to fetch content ot report events to Target edge servers

POST Request

The Server Side Delivery API only supports POST requests.  Here is a sample POST call performed using the API.

https://your-client-code.tt.omtrdc.net/rest/v1/mbox/my-session-123?client=your-client-code

where:

my-session-123

Session Id that is generated and maintained by the client. The Session Id can be any printable string except a space, ?, or /. It should be between 1 and 128 characters in length.

For a particular session, its value must stay the same across multiple requests.

Routing to a particular node in the edge cluster is done using Session Id.

The session is active for 30 minutes on the server side. Therefore, clients should not use a different Session Id for a particular tntId/thirdPartyId within 30 minutes of the last request made with the tntId/thirdPartyId. Otherwise, changes to the profile could be inconsistent and unpredictable.

Using the same Session ID with multiple tntIds/thirdPartyIds may cause unpredictable changes to the profiles identified by the tntId/thirdPartyIDs.

your-client-code Your account's client code. This parameter is mandatory for each request.

Full API Example

Here's a sample request:

{
   "mbox" : "home_banner",
   "clicked" : true,
   "tntId" : "12121212.17_01",
   "order" : {
      "total" : 123.99,
      "id" : "123",
      "purchasedProductIds" : [12, 13, 15, "someProductId"]
   },
   "profileParameters" : {
      "param1" : "value1",
      "param2" : "value2"
   },
   "mboxParameters" : {
      "screenHeight" : "800",
      "browserWidth" : "600"
   "requestLocation" : {      
      "pageURL" : "http://demo/demo/store/",      
      "referrerURL" : "http://demo/demo/store/",      
      "ipAddress" : "128.10.10.1",      
      "impressionId" : "15989",      
      "host" : "hostname"   
   },   
   "mboxTrace" : true
}




Sample Response

The response looks like the following:

{
   "sessionId" : "1234",
   "tntId" : "121212121.17_01",
   "mboxTrace" : {
      "mboxName":"homePageFeature1",
      "serverNode":"aneaga",
      "campaigns":[
         {
         "id" : 21,
         "campaignName":"bullseye header",
         "branchId":0,
         "branchName":"Experience A",
         "offers":[38],"metrics":[
      .........
   }
   }
   "content" : "raw content here"
}

Third-Party ID Usage

You can use third party IDs without previously creating them.  For example:

{
   "mbox" : "homePageHero",
   "thirdPartyId" : "clientSpecificId",
   "mboxParameters" : {
      "screenHeight" : "800",
      "browserWidth" : "600"
   }
}

If a profile with clientSpecificId was previously created, it is used in the context of this call. Otherwise, a new profile is created using this ID.

All String parameters in the request will be trimmed.

In case there's no offer to serve, content is an empty string.

Content is always JSON-escaped.  In other words, the request payload should be a valid JSON as per the standard specified in http://www.ietf.org/rfc/rfc4627.txt

Redirect offer content is served using the format: redirectTo:URL-here, for example redirectTo:http://adobe.com

Default content is served as an empty string.

Request Details

Field Path Description Default Value Validation
mbox The mbox name. None, it cannot be empty.

Same validation as for all mbox calls.

1 < Length < 250

Cannot contains any of the following characters: ', ", %22, %27, <, >, %3C, %3E

clicked

Equivalent of using the "-clicked" suffix in mbox names for mbox calls.

Click mboxes only work for campaigns with metrics that have a specific mbox selected, for example "click from homePageHer" and will not work if "click from display mboxes" is selected.

 

False Can be empty or true/false
tntId New name for pcId/mboxPC.

Empty.

If no "thirdPartyId" was provided, a new tntId is generated and returned as part of the response. Otherwise remains empty.

1 < Length < 128

Cannot contain more than a single "." (dot).

The only dot allowed is for profile location suffix.

thirdPartyId Client-provided visitor ID. Empty 1 < Length < 128
marketingCloudVisitorId Marketing Cloud Visitor ID Empty 1 < Length < 128
order.total Order amount associated with the order Empty If not empty, should be a valid decimal
order.id Order reference ID Empty If not empty, Length < 250
order.purchasedProductIds Order referenced product IDs Empty

Each ID cannot exceed 50 char length.

Total length of comma-delimited IDs as string cannot exceed 250 chars

profileParameters

Parameters that should be set in the profile.

The end values in the profile are saved as profile.param=value.

Empty Cannot contain more than 50 parameters
profileParameters.[name] Profile parameter name Empty

Length < 128

Should not start with "profile." prefix.

profileParameters.[value] Profile parameter value Empty Length < 256
mboxParameters Any mbox parameters that may need to be provided. eg. screenWidth. Empty

Cannot contain more than 50 parameters.

Cannot contain order-related parameters that should be set in "order".

Cannot contain parameters with "profile." prefix. Those should be set in "profileParameters".

mboxParameters.[name] Mbox parameter name Empty Length < 128
mboxParameters.[value] Mbox parameter value Empty Length < 256
requestLocation.pageURL Equivalent to mboxURL mbox parameter Empty

Valid URL.

Length < 3072

requestLocation.referrerURL Equivalent to mboxReferrer mbox parameter Empty

Valid URL

Length < 3072

requestLocation.ipAddress Override the IP address of the client server IP address or the server making the call Valid IP address
requestLocation.impressionId

Equivalent of pageId.

A unique one is generated with each request if no value was specified.

Empty Length < 128
requestLocation.host Equivalent of mboxHost "unknown" Length < 250
mboxTrace Enabled detailed tracing of the call False Empty/True/False

Response Description

Field Path Description
sessionId Session ID that was provided for this call.
tntId Provided or generated tntId.
thirdPartyId thirdPartyId if one was provided.
mboxTrace Serialized mbox trace details.

Identifying visitors

There are a couple of ways that visitor information can be passed to Target:

  • The client stores the TnT ID generated by Target
  • The client uses custom IDs to identify visitors (profiles)
  • A Marketing Cloud Visitor ID is used

Using the TnT ID

The client has the possibility to store our generated TnT ID. In this case, the request made is as simple as:
https://mboxedge/rest/v1/mbox/999888?client=demo

Request

{
   "mbox" : "homePageHero"
}

Response

{
   "content" : "content",
   "sessionId" : "999888",
   "tntId" : "1405327173056-274175.01_00"
}

Note that a new tntId is generated and provided in the response.  Subsequent requests need to include this TnT ID:
https://mboxedge/rest/v1/mbox/999888?client=demo

{
   "mbox" : "homePageHero",
   "tntId" : "1405327173056-274175.01_00"
}
Using Custom IDs
If you want to use Custom IDs to identify visitors (profiles), use thirdpartyids only. You must provide these IDs with every call.
https://mboxedge/rest/v1/mbox/999888?client=demo
{
   "mbox" : "homePageHero",
   "thirdPartyId" : "customId-123"
}

Response

{
   "content" : "content",
   "sessionId" : "999888",
   "thirdPartyId" : "customId-123"

Marketing Cloud Visitor ID
{
   "mbox" : "homePageHero",
   "marketingCloudVisitorId" : "23131312312312123123"
}

Combining IDs

You can combine tntId/thirdPartyId/marketingCloudVisitorId and provide them in the same request. . A typical scenario would be to provide tntId along with another ID.

{
   "mbox" : "homePageHero",
   "tntId" : "1234343422.17_01",
   "marketingCloudVisitorId" : "23131312312312123123"
}

Returning Visitors

Calls for returning visitors need to include the identifier that was used initially, tntId or thirdPartyId.

Error Conditions

In case of error conditions:

{
   "status" : 500,
   "message" : "An error has occurred while processing your request, please try again later"
}

Multiple mbox requests in the same call

Product and client integrations sometimes require a way to efficiently make numerous mbox calls and receive responses asynchronously for a particular visitor.

To implement mbox calls in a batch for a visitor, define a generic JSON-based protocol that allows integration with internal Adobe clients, such as Adobe Campaign and external clients. The procotol should be generic enough to allow integration using various transport protocols, such as HTTP, Kafka, and so on.

API URL is "/rest/v1/batchmbox" and supports POST requests only.

The concept of session does not exist in this API.

A "batch" in the context of the API is one or more subsequent "request" objects, within a single POST request. Each batch can contain multiple mboxes.

The API allows several requests within a batch. The maximum limit is determined by the throttling conditions and the 60MB POST limit size on Edge.

A batch call has the following format:

Request

{
    "responseCallback": {
        "metadata": {
            "requestId": "1345",
            "something": "value"
        }
    },
    "apiClientId": "campaign",
    "*tntId/marketingCloudVisitorId/thirdPartyId": "1242343_17.01",
    "*newVisitor": "true/false",
    "imsOrgId/clientCode": "demo",
    "mboxRequests": [
        {
            "name": "homePageHero",
            "profileParameters": {
                "param1": "value1"
            },
            "mboxParameters": {
                "param1": "value1"
            },
            "requestLocation": {
                "host": "hostname"
            }
    },
        {
            "name": "productPage"
    }
  ]
}
Response

{
    "metadata": {
        "requestId": "1345",
        "something": "value"
    },
    "apiClientId": "campaign",
    "tntId/marketingCloudVisitorId/thirdPartyId": "1242343_17.01",
    "mboxResponses": [
        {
            "name": "homePageHero",
            "offers": [
                {
                    "html/redirect/dynamic/actions": "content",
                    "clickToken": "7.8"
        }
      ]
    },
        {
            "name": "productPage"
    }
  ]
}
Error
{
    "name": "homePageHero",
    "error": "Failed to process"
}

In the context of a request, if one mbox processing fails, other mboxes are skipped and the response contains an error:
"Skipped due to previous mbox error".


"name" : "homePageHero",
"error": "Skipped due toprevious mbox error"
}