This article shows how to use Campaign Standard's REST API to perform operations on your database.

Scope

This document describes how to use Adobe Campaign Standard's APIs and provides general guidelines as well as examples on how to implement and use them.

  1. Scenarios for leveraging ACS APIs.
  2. Authenticating via Adobe I/O and generating JWTs (JSON Web Token).
  3. Performing create/read/update/delete (CRUD) operations on a profile using ACS APIs. (Hands on Exercise) 
  4. Subscribing and Unsubscribing a profile from a service using ACS APIs. (Hands on Exercise) 
  5. Integrating the APIs into a Demo website. (Example) 

 

Prerequisites

A marketing business user for ACS APIS should have some understanding of the following: 

  1. Purpose of API calls. 
  2. Use cases for making API calls. 
  3. Applying technical solutions to solve real-world problems. 

A developer for ACS APIs should have appropriate privileges and knowledge of the following: 

  1. Purpose and usage of REST APIs.
  2. Administrative privileges of ACS.
  3. Adobe.IO authentication set up steps and knowledge of generating JWT tokens.

Reference Materials

The following articles are good reference materials on ACS APIs and related technology framework, including Adobe I/O. 

Real world example for ACS APIs

Adobe Campaign Standard provides APIs which allow existing systems to integrate with the ACS platform to solve real-world problems in real-time. Public websites like the sign-up or opt-out page need to connect to backend systems to store profile information. Backend systems like Adobe Campaign have the flexibility and power to ingest profile data into and perform custom operations on it. 

Sign-up Landing Page and Preference Center

The sign up page – from a sample website Geometrixx – provides a way for customers or prospects to register their name and email address. Once ACS captures the profile information and preferences, ACS can send personalized messages based on the person’s interests. 

1. A registration form with campaign API listeners.

L4281_1

2. Custom actions to be taken based on checkboxes. A customer selecting “Email Special Offers” would be sent a different custom mail with a gift coupon compared to normal registration process.

L4281_2

3. A profile may change their details after clicking on the “Update Details” link in the email. This brings the profile to the “Update your Profile and Preference Details” page. To perform the operation, the profile details (Pkey) are passed to the Campaign server and the profile is retrieved and represented. Once the profile clicks on “Update” button, the information is updated into the system (via PATCH command). 

L4281_3

This document primarily focuses on enabling developers to use ACS APIs in scenarios like above and help you create successful e-mail campaigns and systems. 

Why using ACS APIs?

Business Purpose

Integrate the Campaign Standard platform with website and/or other business systems (order processing, transactional systems, POS, etc.) to perform real-time customer profile synchronization and trigger messages. 


Here are some examples: 

  • Prospects online registration.
  • Existing customer profile and marketing communication preference management.
  • Event based transactional communication triggering – order confirmation, booking Itinerary, password reset, etc.
  • Even cart abandonment email communication.

Technical Solution

ACS APIs enable developers and programmers to perform the following operations seamlessly:

  1. Synchronize data in real-time.
    1. Perform CRUD operations on Profiles and Services. 
    2. Subscribe profiles to a service and Unsubscribe from it. 
  2. Message triggering in real-time.
    1. Send custom event based emails or SMS to profiles based on their actions. 

Setup

Authenticating with Adobe and generating the access token

Adobe Campaign APIs require an “API key” and a “user token” to authenticate users requesting APIs. This section describes how the Administrator of the Marketing Cloud Organization would do the one-time setup of Adobe.IO to integrate with ACS APIs. 

Configuring Adobe.IO to use public token to access ACS APIs

1. Sign into Adobe I/O console (https://www.adobe.io/console) and choose your IMS organization from the organization drop down. Then select New integration.

Screen Shot 2017-05-22 at 11.52.09

2. Select the type of integration you want to configure. Here, select Access an API and click Continue.

Screen Shot 2017-05-22 at 11.58.58

3. Select Adobe Campaign in the list of possible integrations, under the Marketing Cloud section, and click Continue.

Screen Shot 2017-05-22 at 12.10.27

4. Select New integration and click Continue.

Screen Shot 2017-05-22 at 12.15.11

5. Enter the details needed to create the new integration:

  • Indicate the integration Name and Description.
  • Register certificates into Adobe I/O by uploading your public key. The keys would be later used while generating JWTs. Your keys should be .crt files.
  • Choose the Campaign service to use. This list is made of Campaign user groups available for the organization that you selected at the first step.

Then click Create integration.

The integration is automatically created and you are now able to access its details.

Screen Shot 2017-05-22 at 12.21.19
Screen Shot 2017-05-22 at 12.25.53

6. Preserve the following credentials to generate the JWT. 

  • API key
  • Client secret 
  • Technical account ID 
  • Organization ID.
Screen_Shot_2017-05-22_at_12_36_11
Screen_Shot_2017-05-22_at_12_36_40

Generating Token with JWT

To consume ACS APIs Access tokens, are provided for user Authentication. Use the credentials preserved above to generate JWT. A sample Python script is given below to generate JWT. 
Other languages are supported by the open source community.

For more information, refer to this page: https://www.adobe.io/apis/cloudplatform/usermanagement/docs/setup.html 

import sys
if sys.version_info[0] ==2:
from ConfigParser import RawConfigParser
from urllib import urlencode
elif sys.version_info[0] >=3:
from configparser import RawConfigParser
from urllib.parse import urlencode
import time
import jwt
import requests
import json
import email.utils
import math
import random
expiry = int(time.time()) + 60*60*24
payload = {
"https://ims-na1.adobelogin.com/s/ent_campaign_sdk" : True,
"exp" : expiry,
"iss" : "<Organization ID> ", // Example : 3CAF2DEA571E82A87F000101@AdobeOrg
"sub" : "<Technical account ID> ", // Example : A5714DE558B7A30C0A495C3A@techacct.adobe.com "aud" : https://ims-na1.adobelogin.com/c/< API key> // Example : 43e61e5733c34c2882d0b4af9580016f
}
priv_file = open("<Path to private key>") // Example : ‘C:/Users/njia/Work/API/ACS API/private.key’
priv_key = priv_file.read()
priv_file.close()
jwt_token = jwt.encode(payload, priv_key, algorithm='RS256')
jwt_token = jwt_token.decode("utf-8")
print(jwt_token)

Access Token

You need to generate and use a token to perform REST operations. 

References 


Learn about the Authentication Process and Token generation: https://www.adobe.io/apis/cloudplatform/usermanagement/docs/setup.html 

Generating JSON Web tokens is essential to use the APIs. 

About Postman

To showcase the use of APIs, the procedures of this document use the Postman tool for REST calls. 

  • Make sure you can launch postman on your desktop (install Chrome plugin): https://chrome.google.com/webstore/detail/postman/fhbjgbiflinjbdggehcddcbncdddomop?hl=en 
  • Importing JSON collection with all the POSTMAN samples (3 files, one per instance), shared via email.
  • Each JSON collection will have:
    • Hard-coded API Key.
    • Correct URL for API endpoint which includes tenant name.
    • Pre-configured Event Name for use in real-time messaging (same across three instances).
  • Access token must be pasted into POSTMAN. 

Synchronizing Data in Real-Time

The APIs enable developers to perform the following CRUD operations on a profile:

  1. Add a profile.
  2. Fetch a profile from an email id. 
  3. Modify a profile. 
  4. List Services in an account.
  5. Subscribe a profile to a service. 
  6. Unsubscribe a profile from a service. 

Lesson 1 - Add a Profile

1. Launch POSTMAN and import a collection (provided in the assets available at the bottom of this page).

L4281_12

2. Open REST API call “ACS Profile Insert” and observe the values of request headers. 

L4281_13

3. X-Api-Key and URL should be set based on your instance.

4. Set Authorization based on the token you have generated.

L4281_14

5. Hit the “Send” button. 

6. Validate results in output window (JSON object) Post Body. 

L4281_15

The request’s response is shown below - The unique ley associated with all the objects associated in ACS system is called as PKey. Once a profile is created the response contains PKey along with other attributes. 

L4281_16

7. Profile verification. Log into ACS instance and see that profile has been created.

  • Log into ACS with given credentials and navigate to “Profiles” in top header bar. 
L4281_17
  • Search by email address for your profile. 
    • Click on “Show search” icon in top left under “Adobe Campaign”.
L4281_18
  • Enter search criteria by email. In this case sample@adobe.com. 
  • Click enter and results show in right pane. 
L4281_19
  • Validate results.
L4281_20

To summarize the POST profile, the API call is constructed as follows:

API - https://mc.adobe.io/<tenant_name>/campaign/profileAndServicesExt/profile/ 

Request Headers:

  • X-Api-Key: Value of API Key provisioned by Adobe I/O
  • Authorization: Access token in the format of “Bearer”. 
  • Cache Control: no-cache (Recommended, to avoid content caching issues).
  • Content-Type: application/json – The request expects the payload in JSON format. 

Request Method – POST

 
Request Body
The request body needs to be a JSON blob comprising of profile information:

{
"email":"hello@abd.com",
"cusCustomer_ID":"Adobe1000003",
"firstName":"Hello",
"lastName":"World"
}

Response Body

{
"PKey": “@YDiPuQnFDXw_QJhpYrDS08PihTZGn88AszVPWMNLlM1smuI8hYnGwxCGo9CcvrhxnKhf2ZeF4mLWBqKlPYvvfR5lZac",
"age": 0,
"birthDate": ""
}

Lesson 2 – Fetch a Profile from an Email Address

A profile can be searched and retrieved using GET method on ACS API.

API - https://mc.adobe.io/<tenant_name>/campaign/profileAndServicesExt/profile/byEmail?email=abcd@adobe.com 

Request Headers:

  • X-Api-Key: Value of API Key provisioned by Adobe I/O
  • Authorization: Access token in the format of “Bearer”. 
  • Cache Control: no-cache (Recommended, to avoid content caching issues).

Request Method – GET

 
Response Body
The response body has a JSON blob comprising of profile information. As shown in the image below with the PKey and other profile keys and values. 

L4281_21

Lesson 3 - Update a Profile

L4281_22

A profile can be updated using PATCH method on ACS API.

Search for a profile using its email address. Get the PKey value as stated in the lesson above and use the PKey to update the profile. 

API - https://mc.adobe.io/<tenant_name>/campaign/profileAndServicesExt/profile/ 

Request Headers

  • X-Api-Key: Value of API Key provisioned by Adobe I/O.
  • Authorization: Access token in the format of “Bearer”.
  • Cache Control: no-cache (Recommended, to avoid content caching issues).
  • Content-Type: application/json – The request expects the payload in JSON format. 

Request Method – PATCH 


Request Body 
The request body needs to be a JSON blob comprising of specific information which needs to be updated.


Response Body 
The response body comprises of PKey and the profile URI as shown in the image below. 

L4281_23

To check the changes, use the href in the response body. 

Lesson 4 – Get the list of subscriptions for a Profile

A profile can be searched and retrieved using GET method on ACS API.


API - https://mc.adobe.io/<tenant_name>/campaign/profileAndServicesExt/profile/<profile_pkey>/subscriptions 

Request Headers

  • X-Api-Key: Value of API Key provisioned by Adobe I/O.
  • Authorization: Access token in the format of “Bearer”.
  • Cache Control: no-cache (Recommended, to avoid content caching issues).

Request Method – GET

Response Body 
The response body has a JSON blob comprising list of subscriptions for the profile. 

Lesson 5 – List services

To list all the services in an account use, GET method to call service API .


API – https://mc.adobe.io/<instance name>.adobe.com/campaign/profileAndServices/service 

Request Headers

  • X-Api-Key: Value of API Key provisioned by Adobe I/O.
  • Authorization: Access token in the format of “Bearer”.
  • Cache Control: no-cache (Recommended, to avoid content caching issues).

Request Method

L4281_24

Lesson 6 – Subscribe a Profile to a Service

A profile can be subscribed to a service by POSTing its PKey to the following API .

API - https://mc.adobe.io/<tenant_name>/campaign/profileAndServices/service/<service_id>/subscriptions  

Request Headers

  • X-Api-Key: Value of API Key provisioned by Adobe I/O.
  • Authorization: Access token in the format of “Bearer”.
  • Cache Control: no-cache (Recommended, to avoid content caching issues).
  • Content-Type: application/json – The request expects the payload in JSON format. 

Request Method – POST 


Request Body 
The request body needs to be a JSON blob comprising a profile’s PKey.

{
"subscriber":{"PKey": " @YDiPuQnFDXw_QJhpYrDS08PihTZGn88AszVPWMNLlM1smuI8hYnGwxCGo9CcvrhxnKhf2ZeF4mLWBqKlPYvvfR5lZac"}
}

Lesson 7 – Unsubscribe a Profile from a Service

A profile can be unsubscribed from a service by calling DELETE method on the service API and passing the profile PKey. 


API - https://mc.adobe.io/<tenant_name>/campaign/profileAndServices/service/<service_id>/subscriptions 

Request Headers

  • Authorization: Access token in the format of “Bearer”.
  • Content-Type: application/json – The request expects the payload in JSON format. 

Request Method – DELETE 


Request Body 
The request body needs to be a JSON blob comprising a profile’s PKey.

{
"subscriber":{"PKey": " @YDiPuQnFDXw_QJhpYrDS08PihTZGn88AszVPWMNLlM1smuI8hYnGwxCGo9CcvrhxnKhf2ZeF4mLWBqKlPYvvfR5lZac"}
}

Lesson 8 – Triggering email based on real-time events

We can trigger an email based on a customer's action. An event handle can call the POST method on a custom registered Campaign event to perform a desired action at its occurrence. 


API - https://<instance name>.adobe.com/rest/<instanace id>/Form_Registration 

Request Headers

  • Authorization: Access token in the format of “Bearer”.
  • Content-Type: application/json – The request expects the payload in JSON format. 

Request Method – POST 


Request Body 
The request body needs to be a JSON blob comprising a profile’s PKey.

{
"email": "hw@adobe.com",
"ctx":
{
"MOBILE": "111",
"Email": "hw@adobe.com",
"FNAME": "Xaxaxa"
}
}

Lesson 9 - Trigger SMS based on real-time events

We can trigger an SMS based on a customer's action. An event handle can call the POST method on a custom registered Campaign event to perform a desired action at its occurrence. 


API - https://<instance name>.adobe.com/rest/<instance id>/EVTsms_trigger 

Request Headers

  • Authorization: Access token in the format of “Bearer”.
  • Content-Type: application/json – The request expects the payload in JSON format. 

Request Method – POST 


Request Body 
The request body needs to be a JSON blob comprising a profile’s PKey.

{
"mobilePhone":"+9197####5013",
"ctx":
{
"mobile":"+919711##5013",
"coupon":2147483647,
"fname":"Hello",
"email":”helloworld@adobe.com”
}
}

Изтегляне

Този материал е лицензиран под лиценз Creative Commons Attribution-Noncommercial-Share Alike 3.0 Unported  Публикациите в Twitter™ и Facebook не попадат под клаузите на Creative Commons.

Правни бележки   |   Правила за онлайн поверителност