In order to call any Campaign API, you need to create a client object first using the sdk.init function. You pass it the Campaign URL, as well as your credentials.
const sdk = require('@adobe/acc-js-sdk');
const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
"https://myInstance.campaign.adobe.com",
"admin", "admin");
const client = await sdk.init(connectionParameters);
Additional parameters can be passed when creating a connection. The connection parameters are described here.
const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
"https://myInstance.campaign.adobe.com",
"admin", "admin",
{ representation: "xml", rememberMe: true });
After a client object has been created, it's time to log on to Campaign. The sdk.init call will not actually connect to Campaign, you can call the logon method for this. Logon does not need to be called when using session-token authentication or anonymous authentication.
await client.logon();
It's also best practice to logoff when finished
await client.logoff();
upon return, the logon function returns a lot of useful information
The most convenient way to access this information is by using the Application object, but you can also use the client.getSessionInfo().serverInfo and client.getSessionInfo().sessionInfo calls.
Note: depending on the type of credentials used, user and server info may not be returned.
| Credentials Type | Returns info |
|---|---|
| UserPassword | Yes |
| ImsServiceToken | Yes |
| SessionToken | No |
| AnonymousUser | No |
| SecurityToken | Yes |
| BearerToken | Yes |
| ImsBearerToken | No |
There are several methods of the sdk.ConnectionParameters depending on the type of authentication you want to use. They are described below.
This is the most common method to log in to Campaign. Use the ofUserAndPassword function and pass it the user name and password
const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
"https://myInstance.campaign.adobe.com",
"admin", "admin");
In Campaign 8.5 and above, native support for IMS bearer tokens is avaiable and can be used in the SDK as the preferred connection method.
const connectionParameters = sdk.ConnectionParameters.ofImsBearerToken(
"https://myInstance.campaign.adobe.com",
"ims_bearer_token");
Note: You still need to call Logon
With this authentication method, an IMS Bearer token is obtained outside of Campaign, for example using IMS APIs and is passed directly to all Campaign APIs. Campaigns itslef will verify the token and grant the corresponding access.
For older versions of Campaign, you can still use IMS tokens with the ofBearerToken function. The difference between ofImsBearerToken and ofBearerToken is that ofBearerToken will internally call "xtk:session#BearerTokenLogon" to exchange the IMS token for Campaign session and security tokens. Subsequent API calls will use Campaign tokens. It's recommended to us ofImsBearerToken logon whenever possible.
const connectionParameters = sdk.ConnectionParameters.ofBearerToken(
"https://myInstance.campaign.adobe.com",
"ims_bearer_token");
One caveat with ofImsBearerToken mechanism is that logon will not actually call any SOAP logon APIs. The bearer token is just stored in memory and will be passed along with subsequent calls.
This can be a concern because "xtk:session#Logon" and "xtk:session#BearerTokenLogon" return a session info object containing information about the server and the logged user. This includes the server version and build number, the list of active packages, etc. This information is not available when using ofImsBearerToken.
In Version 1.1.35 of the SDK, it is possible to get this information consistently with other Logon method by passing the "sessionInfo" option to the ofImsBearerToken call.
const connectionParameters = sdk.ConnectionParameters.ofImsBearerToken(
"https://myInstance.campaign.adobe.com",
"ims_bearer_token",
{ sessionInfo: true });
Campaign supports authenticating with a session token in some contexts. This is usually used for Message Center API calls (see the Message Center section). In the following example, the session token is a string composed of the user name, a slash sign, and the password (often empty)
const connectionParameters = sdk.ConnectionParameters.ofSessionToken(url, "mc/mc");
Note that this authentication mode is very specific and does not actually performs a Logon: the session token will be passed to each API calls as-is (with an empty security token) and requires proper setup of the security zones for access to be granted.
Another consequence is that the Application object will not be available (client.application will be undefined) when using this authentication mode. The reason is that the application object requires an actual login call to be made to be populated.
Several Campaign APIs are anonymous, i.e. do not require to actually logon to be used. For instance the /r/test API is anonymous. The SDK supports anonymous APIs but still need to be initialized with anonymous credentials as follows. Of course, anonymous APIs also work if you are logged on with a different method.
const connectionParameters = sdk.ConnectionParameters.ofAnonymousUser(url); const client = await sdk.init(connectionParameters);
If you want to use the SDK client-side in a web page returned by Campaign, you cannot use the previous authentication functions because you do not know the user and password, and because you cannot read the session token cookie.
For this scenario, the `ofSecurityToken` function can be used. Pass it a security token (usually available as document.__securitytoken), and the SDK will let the browser handle the session token (cookie) for you.
<script src="acc-sdk.js"></script>
<script>
(async () => {
try {
const sdk = document.accSDK;
var securityToken = "@UyAN...";
const connectionParameters = sdk.ConnectionParameters.ofSecurityToken(url, securityToken);
const client = await sdk.init(connectionParameters);
await client.logon();
const option = await client.getOption("XtkDatabaseId");
console.log(option);
} catch(ex) {
console.error(ex);
}
})();
</script>
</body>
</html>
Note: if the HTML page is served by the Campaign server (which is normally the case in this situation), you can pass an empty url to the `ofSecurityToken` API call.
The SDK also supports IMS service token with the ofUserAndServiceToken function. Pass it a user to impersonate and the IMS service token.
In that context, the IMS service token grants admin-level privileges, and the user indicates which Campaign user to impersonate.
const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
"https://myInstance.campaign.adobe.com",
"admin", "==ims_service_token_here");
This ability is reserved for Adobe services only.
The refreshClient is an async callback function with the SDK client as parameter, it is called when the ACC session is expired. The callback must refresh the client session and return it. if a SOAP query fails with session expiration error then it will be retried when the callback is defined.
const connectionParameters = sdk.ConnectionParameters.ofUserAndPassword(
url, "admin", "admin",
{ refreshClient: async (client) => {
await client.logon();
return client;
}});
Campaign includes an IP whitelisting component which prevents connections from unauthorized IP addresses. This is a common source of authentication errors.
A node application using the SDK must be whitelisted to be able to access Campaign. The SDK sdk.ip function is a helper function that can help you find the IP or IPs which need to be whitelisted.
This API is only meant for troubleshooting purposes and uses the https://api.db-ip.com/v2/free/self service.
const ip = await sdk.ip();
Will return something like
{ "ipAddress":"AAA.BBB.CCC.DDD","continentCode":"EU","continentName":"Europe","countryCode":"FR","countryName":"France","stateProv":"Centre-Val de Loire","city":"Bourges" }