Edit in GitHubLog an issue

AAM segments

Adobe Audience Manager segments can be leveraged via Adobe Target SDKs. In order to leverage AAM segments, the following fields need to be provided:

NOTE: AAM segments are not supported for on-device decisioning activities.

Field NameRequiredDescription
locationHintYesDCS Location Hint is used to determine which AAM DCS Endpoint to hit in order to retrieve the profile. Must be >= 1.
marketingCloudVisitorIdYesMarketing Cloud Visitor ID
blobYesAAM Blob is used to send additional data to AAM. Must not be blank and the size <= 1024.

The SDK will automatically populate these fields for you when making a getOffers method call, but you will need to ensure a valid visitor cookie is provided. In order to get this cookie, you need to implement VisitorAPI.js in the browser.

Implementation Guide#

Use of Cookies#

Cookies are used to correlate Adobe Audience Manager requests with Adobe Target requests. These are the cookies used in this implementation.

CookieNameDescription
visitor cookieAMCVS_XXXXXXXXXXXXXXXXXXXXXXXX%40AdobeOrgThis cookie is set by VisitorAPI.js when it is initialized with visitorState from the target getOffers response.
target cookiemboxYour web server must set this cookie using the name and value of targetCookie from the target getOffers response.

Overview of steps#

Suppose a user enters a URL into a browser which sends a request to your web server. When fulfilling that request...

  1. The server reads the visitor and target cookies from the request.
  2. The server makes a call to the getOffers method of the Target SDK, specifying the visitor and target cookies if available.
  3. When the getOffers call is fulfilled, values for targetCookie and visitorState from the response are used.
    1. A cookie is set on the response with values taken from targetCookie. This is done using the Set-Cookie response header, which tells the browser to persist the target cookie.
    2. An HTML response is prepared that initializes VisitorAPI.js and passes in visitorState from the target response.
  4. The HTML response is loaded in the browser...
    1. VisitorAPI.js is included in the document header.
    2. VisitorAPI is initialized with visitorState from the getOffers SDK response. This will cause the visitor cookie to be set in the browser so it will be sent to the server on subsequent requests.

Example code#

The following code sample implements each of the steps outlined above. Each step appears in the code as an inline comment next to its implementation.

Node.js#

This sample relies on express, a Node.js web framework.

server.js

Copied to your clipboard
1const fs = require("fs");
2const express = require("express");
3const cookieParser = require("cookie-parser");
4const Handlebars = require("handlebars");
5const TargetClient = require("@adobe/target-nodejs-sdk");
6
7const CONFIG = {
8 client: "acmeclient",
9 organizationId: "1234567890@AdobeOrg",
10 timeout: 10000,
11 logger: console,
12};
13const targetClient = TargetClient.create(CONFIG);
14const TEMPLATE = fs.readFileSync(`${__dirname}/index.handlebars`).toString();
15const handlebarsTemplate = Handlebars.compile(TEMPLATE);
16
17Handlebars.registerHelper("toJSON", function (object) {
18 return new Handlebars.SafeString(JSON.stringify(object, null, 4));
19});
20
21const app = express();
22app.use(cookieParser());
23app.use(express.static(__dirname + "/public"));
24
25app.get("/", async (req, res) => {
26 // The server reads the visitor and target cookies from the request.
27 const visitorCookie =
28 req.cookies[
29 encodeURIComponent(
30 TargetClient.getVisitorCookieName(CONFIG.organizationId)
31 )
32 ];
33 const targetCookie = req.cookies[TargetClient.TargetCookieName];
34 const address = { url: req.headers.host + req.originalUrl };
35
36 const targetRequest = {
37 execute: {
38 mboxes: [
39 { name: "homepage", index: 1, address },
40 { name: "SummerShoesOffer", index: 2, address },
41 { name: "SummerDressOffer", index: 3, address }
42 ],
43 },
44 };
45
46 res.set({
47 "Content-Type": "text/html",
48 Expires: new Date().toUTCString(),
49 });
50
51 try {
52 // The server makes a call to the `getOffers` method of the Target SDK specifying the visitor and target cookies if available.
53 const targetResponse = await targetClient.getOffers({
54 request: targetRequest,
55 visitorCookie,
56 targetCookie,
57 });
58
59 // When the `getOffers` call is fulfilled, values for `targetCookie` and `visitorState` from the response are used.
60 // A cookie is set on the response with values taken from `targetCookie`. This is done using the `Set-Cookie` response header which tells the browser to persist the target cookie.
61 res.cookie(
62 targetResponse.targetCookie.name,
63 targetResponse.targetCookie.value,
64 { maxAge: targetResponse.targetCookie.maxAge * 1000 }
65 );
66
67 // An HTML response is prepared that initializes VisitorAPI.js and passes in `visitorState` from the target response.
68 const html = handlebarsTemplate({
69 organizationId: CONFIG.organizationId,
70 targetResponse,
71 });
72
73 res.status(200).send(html);
74 } catch (error) {
75 console.error("Target:", error);
76 res.status(500).send(error);
77 }
78});
79
80app.listen(3000, function () {
81 console.log("Listening on port 3000 and watching!");
82});

index.handlebars

Copied to your clipboard
1<!doctype html>
2<html>
3<head>
4 <meta charset="UTF-8">
5 <title>ECID (Visitor API) Integration Sample</title>
6
7 <!-- VisitorAPI.js is included in the document header. -->
8 <script src="VisitorAPI.js"></script>
9 <script>
10 // VisitorAPI is initialized with visitorState from the `getOffers` SDK response. This will cause the visitor cookie to be set in the browser so it will be sent to the server on subsequent requests.
11 Visitor.getInstance("{{organizationId}}", {serverState: {{toJSON targetResponse.visitorState}} });
12 </script>
13</head>
14<body>
15 <h1>response</h1>
16 <pre>{{toJSON targetResponse}}</pre>
17</body>
18</html>

Java#

This sample uses spring, a Java web framework.

ClientSampleApplication.java

Copied to your clipboard
1@SpringBootApplication
2public class ClientSampleApplication {
3
4 public static void main(String[] args) {
5 System.setProperty(SimpleLogger.DEFAULT_LOG_LEVEL_KEY, "DEBUG");
6 SpringApplication.run(ClientSampleApplication.class, args);
7 }
8
9 @Bean
10 TargetClient marketingCloudClient() {
11 ClientConfig clientConfig = ClientConfig.builder()
12 .client("acmeclient")
13 .organizationId("1234567890@AdobeOrg")
14 .defaultDecisioningMethod(DecisioningMethod.SERVER_SIDE)
15 .build();
16
17 return TargetClient.create(clientConfig);
18 }
19}

TargetController.java

Copied to your clipboard
1@Controller
2@RequestMapping("/")
3public class TargetController {
4
5 @Autowired
6 private TargetClientService targetClientService;
7
8 @GetMapping
9 public String index(Model model, HttpServletRequest request, HttpServletResponse response) {
10 // The server reads the visitor and target cookies from the request.
11 List<TargetCookie> targetCookies = getTargetCookies(request.getCookies());
12
13 Address address = getAddress(request);
14
15 List<MboxRequest> mboxRequests = new ArrayList<>();
16 mboxRequests.add((MboxRequest) new MboxRequest().name("homepage").index(1).address(address));
17 mboxRequests.add((MboxRequest) new MboxRequest().name("SummerShoesOffer").index(2).address(address));
18 mboxRequests.add((MboxRequest) new MboxRequest().name("SummerDressOffer").index(3).address(address));
19
20 TargetDeliveryResponse targetDeliveryResponse = targetClientService.getOffers(mboxRequests, targetCookies, request,
21 response);
22
23 // An HTML response is prepared that initializes VisitorAPI.js and passes in `visitorState` from the target response.
24 model.addAttribute("visitorState", targetDeliveryResponse.getVisitorState());
25 model.addAttribute("targetResponse", targetDeliveryResponse);
26 model.addAttribute("organizationId", "1234567890@AdobeOrg");
27
28 return "index";
29 }
30}

TargetClientService.java

Copied to your clipboard
1@Service
2public class TargetClientService {
3
4 private final TargetClient targetJavaClient;
5
6 public TargetClientService(TargetClient targetJavaClient) {
7 this.targetJavaClient = targetJavaClient;
8 }
9
10 public TargetDeliveryResponse getOffers(List<MboxRequest> executeMboxes, List<TargetCookie> cookies, HttpServletRequest request, HttpServletResponse response) {
11
12 Context context = getContext(request);
13 ExecuteRequest executeRequest = new ExecuteRequest();
14 executeRequest.setMboxes(executeMboxes);
15
16 TargetDeliveryRequest targetDeliveryRequest = TargetDeliveryRequest.builder()
17 .context(context)
18 .execute(executeRequest)
19 .cookies(cookies)
20 .build();
21
22 // The server makes a call to the `getOffers` method of the Target SDK specifying the visitor and target cookies if available.
23 TargetDeliveryResponse targetResponse = targetJavaClient.getOffers(targetDeliveryRequest);
24
25 // When the `getOffers` call is fulfilled, values for `targetCookie` and `visitorState` from the response are used.
26 // A cookie is set on the response with values taken from `targetCookie`. This is done using the `Set-Cookie` response header which tells the browser to persist the target cookie.
27 setCookies(targetResponse.getCookies(), response);
28 return targetResponse;
29 }
30}

TargetRequestUtils.java

index.html

Copied to your clipboard
1<!DOCTYPE HTML>
2<html xmlns:th="http://www.thymeleaf.org">
3<head>
4 <meta charset="UTF-8">
5 <title>Target Only : GetOffer</title>
6
7 <!-- VisitorAPI.js is included in the document header. -->
8 <script src="../../js/VisitorAPI.js"></script>
9 <script th:inline="javascript">
10 // VisitorAPI is initialized with visitorState from the `getOffers` SDK response. This will cause the visitor cookie to be set in the browser so it will be sent to the server on subsequent requests.
11 Visitor.getInstance(/*[[${organizationId}]]*/ "", {serverState: /*[[${visitorState}]]*/ {}});
12 </script>
13</head>
14<body>
15 <h1>response</h1>
16 <pre>[[${targetResponse}]]</pre>
17</body>
18</html>
Was this helpful?
  • Privacy
  • Terms of Use
  • Do not sell my personal information
  • AdChoices
Copyright © 2022 Adobe. All rights reserved.