node package manager

@adobe/target-node-client

Marketing Cloud Client

Marketing Cloud Client allows clients to execute requests against Adobe edge network and retrieve personalized content that can be used to enhance user experience. Behind the scenes Marketing Cloud Client wraps two of the Adobe Marketing Cloud solutions, MCID (Marketing Cloud Identity Service) also known as Visitor API and Adobe Target also known as TNT.

Super simple to use

Marketing Cloud Client has been designed to be the simplest way to interact with Adobe Target delivery API.

const MarketingCloudClient = require("@adobe/target-node-client");
 
const marketingCloudClient = MarketingCloudClient.create({
  config: {
    client: "acmeclient",
    organizationId: "1234567890@AdobeOrg",
    timeout: 5000
  }
});
 
marketingCloudClient.getOffer({
  payload: {
    mbox : "some-mbox"
  }
})
.then(offer => console.log('Offer', offer))
.catch(error => console.error('Error', error));

Table of contents

Standalone

Marketing Cloud Client can be used to retrieve personalized content from TNT without being forced to use MCID.

const MarketingCloudClient = require("@adobe/target-node-client");
 
const marketingCloudClient = MarketingCloudClient.create({
  config: {
    client: "acmeclient",
    organizationId: "1234567890@AdobeOrg",
  }
});
 
marketingCloudClient.getOffer({
  payload: {
    mbox : "server-side-mbox"
  }
})
.then(offer => console.log('Offer', offer))
.catch(error => console.error('Error', error));

By default Marketing Cloud Client would generate a new session ID for every TNT call which might not always be the desired behavior. To make sure that TNT properly tracks user session we should make sure TNT cookie is sent to the browser when TNT content is retrieved and TNT cookie value is passed to getOffer() when a request is processed. In an Express application we could have something like this:

const express = require("express");
const cookieParser = require("cookie-parser");
const MarketingCloudClient = require("@adobe/target-node-client");
const CONFIG = {
  client: "acmeclient",
  organizationId: "1234567890@AdobeOrg"
};
 
const marketingCloudClient = MarketingCloudClient.create({config: CONFIG});
const app = express();
 
app.use(cookieParser());
 
function saveCookie(res, cookie) {
  if (!cookie) {
    return;
  }
 
  res.cookie(cookie.name, cookie.value, {maxAge: cookie.maxAge * 1000});
}
 
function sendSuccessResponse(res, offer) {
  res.set({
    "Content-Type": "text/html",
    "Expires": new Date().toUTCString()
  });
 
  saveCookie(res, offer.targetCookie);
 
  res.status(200).send(offer);
}
 
function sendErrorResponse(res, error) {
  res.set({
    "Content-Type": "text/html",
    "Expires": new Date().toUTCString()
  });
 
  res.status(500).send(error);
}
 
app.get("/abtest", function (req, res) {
  const targetCookieName = encodeURIComponent(MarketingCloudClient.getTargetCookieName());
  const targetCookie = req.cookies[targetCookieName];
  const payload = {"mbox" : "server-side-mbox"};
  const request = Object.assign({payload}, {targetCookie});
 
  console.log("Request", request);
 
  marketingCloudClient.getOffer(request)
  .then(offer => {
    sendSuccessResponse(res, offer);
  })
  .catch(error => {
    sendErrorResponse(res, error);
  });
});
 
app.listen(3000, function () {
  console.log("Listening on port 3000 and watching!");
});

MCID Integration

While using Marketing Cloud Client for fetching content from TNT can be pretty powerful, the added value of using MCID for user tracking would outweigh using TNT only. MCID allows leveraging all the goodies found in Adobe Experience Cloud like audience sharing, analytics etc. Using TNT and MCID in an Express application is pretty straightforward. MCID has a client side part to it, so we'll have to use a simple template that references MCID JavaScript library. Here is the Express application:

const express = require("express");
const cookieParser = require("cookie-parser");
const MarketingCloudClient = require("@adobe/target-node-client");
const CONFIG = {
  client: "acmeclient",
  organizationId: "1234567890@AdobeOrg"
};
const TEMPLATE = `
<!doctype html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Marketing Cloud Client NodeJS SDK Sample</title>
  <script src="VisitorAPI.js"></script>
  <script>
    Visitor.getInstance("${organizationId}", {serverState: ${visitorState}});
  </script>
</head>
<body>
  <p>${content}</p>
</body>
</html>
`;
const marketingCloudClient = MarketingCloudClient.create({config: CONFIG});
const app = express();
 
app.use(cookieParser());
// We assume that VisitorAPI.js is stored in "public" folder
app.use(express.static(__dirname + "/public"));
 
function saveCookie(res, cookie) {
  if (!cookie) {
    return;
  }
 
  res.cookie(cookie.name, cookie.value, {maxAge: cookie.maxAge * 1000});
}
 
function sendSuccessResponse(res, offer) {
  res.set({
    "Content-Type": "text/html",
    "Expires": new Date().toUTCString()
  });
 
  const result = TEMPLATE
  .replace("${organizationId}", CONFIG.organizationId)
  .replace("${visitorState}", JSON.stringify(offer.visitorState))
  .replace("${content}", offer.content);
 
  saveCookie(res, offer.targetCookie);
 
  res.status(200).send(result);
}
 
function sendErrorResponse(res, error) {
  res.set({
    "Content-Type": "text/html",
    "Expires": new Date().toUTCString()
  });
 
  res.status(500).send(error);
}
 
app.get("/abtest", function (req, res) {
  const visitorCookieName = encodeURIComponent(MarketingCloudClient.getVisitorCookieName(CONFIG.organizationId));
  const visitorCookie = req.cookies[visitorCookieName];
  const targetCookieName = encodeURIComponent(MarketingCloudClient.getTargetCookieName());
  const targetCookie = req.cookies[targetCookieName];
  const payload = {"mbox" : "server-side-mbox"};
  const request = Object.assign({payload}, {targetCookie}, {visitorCookie});
 
  console.log("Request", request);
 
  marketingCloudClient.getOffer(request)
  .then(offer => {
    sendSuccessResponse(res, offer);
  })
  .catch(error => {
    sendErrorResponse(res, error);
  });
});
 
app.listen(3000, function () {
  console.log("Listening on port 3000 and watching!");
});

The biggest benefit of using MCID integration is that it allows you to share Audience Manager segments with Target. It should be noted that since this is a server side integration for first time visitors we might not have any Audience Manager related data.

MCID and Analytics integration

To get the most of Marketing Cloud Client and use the powerful analytics capabilities provided by Adobe Analytics you can use the MCID, Analytics and TNT combo. Here is a simple Express application that demonstrates how you can use all three solutions in a single application.

const express = require("express");
const cookieParser = require("cookie-parser");
const MarketingCloudClient = require("@adobe/target-node-client");
const CONFIG = {
  client: "acmeclient",
  organizationId: "1234567890@AdobeOrg"
};
const TEMPLATE = `
<!doctype html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Marketing Cloud Client NodeJS SDK Sample</title>
  <script src="VisitorAPI.js"></script>
  <script>
    Visitor.getInstance("${organizationId}", {serverState: ${visitorState}});
  </script>
</head>
<body>
  <p>${content}</p>
  <script src="AppMeasurement.js"></script>
  <script>var s_code=s.t();if(s_code)document.write(s_code);</script>
</body>
</html>
`;
const marketingCloudClient = MarketingCloudClient.create({config: CONFIG});
const app = express();
 
app.use(cookieParser());
// We assume that VisitorAPI.js and AppMeasurement.js is stored in "public" folder
app.use(express.static(__dirname + "/public"));
 
function saveCookie(res, cookie) {
  if (!cookie) {
    return;
  }
 
  res.cookie(cookie.name, cookie.value, {maxAge: cookie.maxAge * 1000});
}
 
function sendSuccessResponse(res, offer) {
  res.set({
    "Content-Type": "text/html",
    "Expires": new Date().toUTCString()
  });
 
  const result = TEMPLATE
  .replace("${organizationId}", CONFIG.organizationId)
  .replace("${visitorState}", JSON.stringify(offer.visitorState))
  .replace("${content}", offer.content);
 
  saveCookie(res, offer.targetCookie);
 
  res.status(200).send(result);
}
 
function sendErrorResponse(res, error) {
  res.set({
    "Content-Type": "text/html",
    "Expires": new Date().toUTCString()
  });
 
  res.status(500).send(error);
}
 
app.get("/abtest", function (req, res) {
  const visitorCookieName = encodeURIComponent(MarketingCloudClient.getVisitorCookieName(CONFIG.organizationId));
  const visitorCookie = req.cookies[visitorCookieName];
  const targetCookieName = encodeURIComponent(MarketingCloudClient.getTargetCookieName());
  const targetCookie = req.cookies[targetCookieName];
  const payload = {"mbox" : "server-side-mbox"};
  const request = Object.assign({payload}, {targetCookie}, {visitorCookie});
 
  console.log("Request", request);
 
  marketingCloudClient.getOffer(request)
  .then(offer => {
    sendSuccessResponse(res, offer);
  })
  .catch(error => {
    sendErrorResponse(res, error);
  });
});
 
app.listen(3000, function () {
  console.log("Listening on port 3000 and watching!");
});

Using MCID, Analytics and TNT allows you:

  • use segments from Audience Manager
  • customize user experience based on the content retrieved from TNT and
  • ensure that all the events and success metrics are collected in Analytics
  • use Analytics powerful queries and benefit from awesome visualizations

at.js integration

Most of the time Marketing Cloud Client will be used in a NodeJS application like Express, Hapi, Koa etc. However with recent proliferation of frameworks that allow server side rendering like Facebook React or Angular 4.x. There are use cases where server side should be aware and work in tandem with client side libraries. In TNT case the client side library is at.js.

The integration between server side and client side is also known as "hybrid" testing mode. The biggest challenge when trying to integrate server side and client side is to ensure that both server side and client side TNT calls are hitting the same TNT edge cluster. Otherwise we may end up with different user profiles being created by server side and client side calls.

To mitigate this TNT uses the so called location hint cookie. To be able to use location hint cookie you'll have to add the following JavaScript to your HTML page before at.js or make sure that this code is executed before at.js, in case you are using a tag manager like Adobe DTM.

window.targetGlobalSettings = {
  overrideMboxEdgeServer: true
};

To see the TNT location hint cookie and at.js integration in action here is a simple Express application:

const express = require("express");
const cookieParser = require("cookie-parser");
const MarketingCloudClient = require("@adobe/target-node-client");
const CONFIG = {
  client: "acmeclient",
  organizationId: "1234567890@AdobeOrg"
};
const TEMPLATE = `
<!doctype html>
<html>
<head>
  <meta charset="UTF-8">
  <title>Marketing Cloud Client NodeJS SDK Sample</title>
  <script src="VisitorAPI.js"></script>
  <script>
    Visitor.getInstance("${organizationId}", {serverState: ${visitorState}});
  </script>
  <script>
    window.targetGlobalSettings = {
      overrideMboxEdgeServer: true
    };
  </script>
  <script src="at.js"></script>
</head>
<body>
  <p>${content}</p>
  <script src="AppMeasurement.js"></script>
  <script>var s_code=s.t();if(s_code)document.write(s_code);</script>
</body>
</html>
`;
const marketingCloudClient = MarketingCloudClient.create({config: CONFIG});
const app = express();
 
app.use(cookieParser());
// We assume that VisitorAPI.js, at.js and AppMeasurement.js is stored in "public" folder
app.use(express.static(__dirname + "/public"));
 
function saveCookie(res, cookie) {
  if (!cookie) {
    return;
  }
 
  res.cookie(cookie.name, cookie.value, {maxAge: cookie.maxAge * 1000});
}
 
function sendSuccessResponse(res, offer) {
  res.set({
    "Content-Type": "text/html",
    "Expires": new Date().toUTCString()
  });
 
  const result = TEMPLATE
  .replace("${organizationId}", CONFIG.organizationId)
  .replace("${visitorState}", JSON.stringify(offer.visitorState))
  .replace("${content}", offer.content);
 
  saveCookie(res, offer.targetCookie);
  saveCookie(res, offer.targetLocationHintCookie);
 
  res.status(200).send(result);
}
 
function sendErrorResponse(res, error) {
  res.set({
    "Content-Type": "text/html",
    "Expires": new Date().toUTCString()
  });
 
  res.status(500).send(error);
}
 
app.get("/abtest", function (req, res) {
  const visitorCookieName = encodeURIComponent(MarketingCloudClient.getVisitorCookieName(CONFIG.organizationId));
  const visitorCookie = req.cookies[visitorCookieName];
  const targetCookieName = encodeURIComponent(MarketingCloudClient.getTargetCookieName());
  const targetCookie = req.cookies[targetCookieName];
  const targetLocationHintCookieName = encodeURIComponent(MarketingCloudClient.getTargetLocationHintCookieName());
  const targetLocationHintCookie = req.cookies[targetLocationHintCookieName];
  const payload = {"mbox" : "server-side-mbox"};
  const request = Object.assign({payload}, {targetCookie}, {visitorCookie}, {targetLocationHintCookie});
 
  console.log("Request", request);
 
  marketingCloudClient.getOffer(request)
  .then(offer => {
    sendSuccessResponse(res, offer);
  })
  .catch(error => {
    sendErrorResponse(res, error);
  });
});
 
app.listen(3000, function () {
  console.log("Listening on port 3000 and watching!");
});

Using at.js integration allows use cases where a TNT experience is started on the server side and is continued on the client side by at.js AKA "hybrid" testing. The downside of this approach is that we might see some performance degradations when NodeJS application that uses Marketing Cloud Client is not GEO distributed as TNT edge clusters.

Troubleshooting

Marketing Cloud Client is a glorified HTTP/HTTPS client, so to understand what is happening on the wire you can provide a logger object. The logger objects is expected to have a log() method that receives a list of parameters. The default logger has a noop log() implementation. To be able to inspect HTTP request and response you can provide a custom logger. Here is an example that shows a logger that logs everything to console:

const fs = require("fs");
const express = require("express");
const cookieParser = require("cookie-parser");
const MarketingCloudClient = require("../lib/index");
 
const CONFIG = {
  client: "acmeclient",
  organizationId: "1234567890@AdobeOrg",
};
 
const logger = getLogger();
const marketingCloudClient = createMarketingCloudClient(logger, CONFIG);
 
function getLogger() {
  return {
    log: function(...arr) {
      console.log(...arr);
    }
  };
}
 
function createMarketingCloudClient(logger, config) {
  const options = Object.assign({logger}, {config});
 
  return MarketingCloudClient.create(options);
}
 
marketingCloudClient.getOffer({
  payload: {
    mbox : "some-mbox"
  }
})
.then(offer => console.log('Offer', offer))
.catch(error => console.error('Error', error));

In case you want to use a more robust logger you can always create a logger that delegates to winston, bunyan or any other well known NodeJS logging library.

Marketing Cloud Client API

MarketingCloudClient.create(options: Object): MarketingCloudClient - creates an instance of Marketing Cloud Client.

The options object has the following structure:

Name Type Required Default Description
config Object Yes None General config
logger Object No NOOP Logger to be used

The config object should have the following structure:

Name Type Required Default Description
client String Yes None Target client
organizationId String Yes None Organization ID
timeout Number No None Target request timeout in milliseconds
secure Boolean No true Target request over HTTP or HTTPS

MarketingCloudClient.getVisitorCookieName(organizationId: string): string - used to retrieve MCID cookie name.

MarketingCloudClient.getTargetCookieName(): string - used to retrieve Target cookie name.

MarketingCloudClient.getTargetLocationHintCookieName(): string - used to retrieve Target location hint cookie name.

MarketingCloudClient.getOffer(request: Object): Promise - fetches an offer from TNT.

The request object has the following structure:

| Name | Type | Required | Default | Description | |--------------------------|----------|--------- |--------------------------------------------| | payload | Object | Yes | None | Server Side Delivery API payload | | targetCookie | String | No | None | Target cookie | | targetLocationHintCookie | String | No | None | Target location hint cookie | | visitorCookie | String | No | None | Visitor cookie |

To learn more about TNT Server Side Delivery API please visit: https://www.adobe.io/apis/marketingcloud/target/docs/reference/delivery.html

The promise returned by MarketingCloudClient.getOffer(...) wraps an offer. The offer object has the following structure:

Name Type Description
targetCookie Object Target cookie
targetLocationHintCookie Object Target location hint cookie
visitorState Object Object that should be passed to Visitor API getInstance()
content String or Object Personalized content, can be string or object

The cookie object used for passing data back to the browser has the following structure:

Name Type Description
name String Cookie name
value Any Cookie value, the value will converted to string
maxAge Number The maxAge option is a convenience option for setting expires relative to the current time in seconds

back to top

Unleash awesomeness

Private packages, team management tools, and powerful integrations. Get started with npm Orgs

how? learn more

Collaborators list

Stats

Keywords

NodeJS, Server, API, Adobe, Target, MCID, Visitor, Delivery

Dependencies (2)

request, uuid