In this exercise, you'll use Postman and Adobe I/O to query Adobe Experience Platform's APIs to view your own real-time customer profile.
Story
In the Real-time Customer Profile, all profile data is shown alongside event data, as well as existing segment memberships. The data shown can come from anywhere, from Adobe applications and external solutions. This is the most powerful view in Adobe Experience Platform, the experience system of record.
The Real-time Customer Profile can be consumed by all Adobe applications, but also by external solutions like Call Centers or in-store clienteling apps. The way to do this is to connect those external solutions to Adobe Experience Platform's APIs.
3.3.1 Your Identifiers
On the Profile Viewer panel on the website, you can find multiple identities. Every Identity is linked to a Namespace.
On the X-ray panel, we can see 4 different combinations of IDs and Namespaces:
Identity
Namespace
Experience Cloud ID (ECID)
12507560687324495704459439363261812234
Email ID
woutervangeluwe+06022022-01@gmail.com
Mobile Number ID
+32473622044+06022022-01
Remember these identifiers for the next step.
With these IDs in mind, go to Postman.
3.3.2 Setup your Adobe I/O Project
In this exercise you'll be using Adobe I/O quite intensively to query against Platform's APIs. Please follow the below steps to setup Adobe I/O.
Make sure to select the correct Adobe Experience Platform instance in the top right corner of your screen. Your instance is --envName--.
Click Create new project.
Select + Add to Project and select API.
You'll then see this:
Click the Adobe Experience Platform icon.
Click Experience Platform API.
Click Next.
You can now choose to either have Adobe I/O generate your security key pair, or upload an existing one.
Choose Option 1 - Generate a key pair.
Click Generate keypair.
You'll see a spinner for about 30 seconds.
You'll then see this, and your generated keypair will be downloaded as a zip file: config.zip.
Unzip the file config.zip on your desktop, you'll see it contains 2 files:
certificate_pub.crt is your Public key certificate. From a security perspective, this is the certificate that is freely used to setup integrations with online applications.
private.key is your Private key. This should never, ever be shared with anyone. The Private Key is what you use to authenticate to your API implementation and is supposed to be a secret. If you share your Private Key with anyone, they can access your implementation and abuse the API to ingest malicious data into Platform and extract all the data that sits in Platform.
Make sure to save the config.zip file in a safe location, as you'll need this for the next steps and for future access to Adobe I/O and Adobe Experience Platform APIs.
Click Next.
You now have to select the Product Profile(s) for your integration.
Select the required Product Profiles.
FYI: in your Adobe Experience Platform instance, the Product Profiles will have a different naming. You need to select at least one product profile with the proper access rights, which are set up in the Adobe Admin Console.
Click Save Configured API.
You'll see a spinner for a couple of seconds.
And next, you'll see your integration.
Click the Download for Postman button and then click Service Account (JWT) to download a Postman environment (wait until the environment is downloaded, this can take a couple of seconds).
Scroll down until you see Service Account (JWT), which is where you can find all your integration details that are used to configure the integration with Adobe Experience Platform.
Your IO Project currently has a generic name. You need to give a friendly name to your integration. Click on Project 1 (or similar name) as indicated
Click Edit Project.
Enter a Name and Description for your integration. As a naming convention, we'll use AEP API --demoProfileLdap--. Replace ldap with your ldap. For instance, if your ldap is vangeluw, the name and description of your integration becomes AEP API vangeluw.
Enter AEP API --demoProfileLdap-- as the Project Title. Click Save.
Your Adobe I/O integration is now finished.
3.3.3 Postman authentication to Adobe I/O
Click on Get Started.
Next, download and install Postman.
After installation of Postman, start the application.
In Postman, there are 2 concepts: Environments and Collections.
The Environment contains all of your environmental variables which are more or less consistent. In the Environment, you'll find things like the IMSOrg of our Platform environment, alongside security credentials like your Private Key and others. The environment file is the one you downloaded during the Adobe I/O setup in the previous exercise, it's name like this: service.postman_environment.json.
The Collection contains a number of API requests that you can use. We will use 2 collections
1 Collection for Authentication to Adobe I/0
1 Collection for the exercises in this module
1 collection for the exercises in the Real-Time CDP module, for Destination Authoring
In this postman.zip file, you'll find the following files:
Unzip the postman.zip file and store these 3 files in a folder on your desktop, together with the downloaded Postman environment from Adobe I/O. You need to have these 4 files in that folder:
Go back to Postman. Click Import.
Click Upload Files.
Navigate to the folder on your desktop in which you extracted the 4 downloaded files. Select these 4 files at the same time and click Open.
After having clicked Open, Postman will show you an overview of the Environment and Collections you're about to import. Click Import.
You now have everything you need in Postman to start interacting with Adobe Experience Platform through the APIs.
The first thing to do, is to make sure you're properly authenticated. To be authenticated, you need to request an access token.
Make sure that you've got the right Environment selected before executing any request. You can check the currently selected Environment by verifying the Environment-dropdown list in the top right corner.
The selected Environment should have a name similar to this one:
Click the eye icon and then click Edit to update the Private Key in the environment file.
You'll then see this. All fields are pre-populated, except for the field PRIVATE_KEY.
The private key has been generated when you created your Adobe I/O Project. It was downloaded as a zip file, named config.zip. Extract that zip file to your desktop.
Open the folder config and open the file private.key with your text editor of choice.
You'll then see something resembling this, copy all the text to your clipboard.
Go back to Postman and paste the private key in the fields next to the variable PRIVATE_KEY, for both the columns INITIAL VALUE and CURRENT VALUE. Click Save.
Your Postman environment and collections are now configured and working. You can now authenticate from Postman to Adobe I/O.
To do that, you need to load an external library that will take care of the encryption and decryption of communication. To load this library, you have to execute the request with the name INIT: Load Crypto Library for RS256. Select this request in the _Adobe I/O - Token collection and you'll see it displayed in the middle of your screen.
Click the blue Send button. After a couple of seconds, you should see a response displayed in the Body section of Postman:
With the crypto library now loaded, we can authenticate to Adobe I/O.
In the _Adobe I/O - Token collection, select the request with the name IMS: JWT Generate + Auth. Again, you'll see the request details displayed in the middle of the screen.
Click the blue Send button. After a couple of seconds, you should see a response displayed in the Body section of Postman:
If your configuration was successful, you should see a similar response that contains the following information:
Adobe I/O has given you a bearer-token, with a specific value (this very long access_token) and an expiration window.
The token that we've received is now valid for 24 hours. This means that after 24 hours, if you want to use Postman to authenticate to Adobe I/O, you will have to generate a new token by running this request again.
Now you can go ahead and send your first request to Platform's Real-time Customer Profile APIs.
In Postman, locate the collection _Adobe Experience Platform Enablement.
In 1. Unified Profile Service, select the first request with the name UPS - GET Profile by Entity ID & NS.
For this request, there are three required variables:
Key
Value
Definition
entityId
id
the specific customer ID
entityIdNS
namespace
the specific namespace that is applicable to the ID
schema.name
_xdm.context.profile
the specific schema for which you want to receive information
So, if you want to ask Adobe Experience Platform's APIs to give you back all Profile information for your own ECID, you will need to configure the request as follows:
Key
Value
entityId
yourECID
entityIdNS
ecid
schema.name
_xdm.context.profile
You should also verify the Header - fields of your request. Go to Headers. You'll then see this:
Key
Value
x-sandbox-name
--aepSandboxId--
[!NOTE]
You need to specify the name of the Adobe Experience Platform sandbox you're using. Your x-sandbox-name should be --aepSandboxId--.
Click Send to send your request to Platform.
You should get an immediate response from Platform, showing you something like this:
This is currently all of the available Profile data in Platform for this ECID.
You're not required to use the ECID to request Profile data from Platform's Real-time Customer Profile, you can use any ID in any namespace to request this data.
Let's go back to Postman and pretend we're the call center, and send a request to Platform specifying the namespace of Phone and your mobile number.
So, if you want to ask Platform's APIs to give you back all Profile information for a specific Phone, you will need to configure the request as follows:
Key
Value
entityId
your phone number
entityIdNS
phone (replace ecid by phone)
schema.name
_xdm.context.profile
If your phone number contains special symbols like +, you have to select your full phone number, do a right-click and click EncodeURIComponent.
You'll then have this:
You should also verify the Header - fields of your request. Go to Headers. You'll then see this:
Key
Value
x-sandbox-name
--aepSandboxId--
[!NOTE]
You need to specify the name of the Adobe Experience Platform sandbox you're using. Your x-sandbox-name should be --aepSandboxId--.
Click the blue Send button and verify the response.
Let's do the same thing for your email address by specifying the namespace of email and your email address.
So, if you want to ask Platform's APIs to give you back all Profile information for a specific email address, you will need to configure the request as follows:
Key
Value
entityId
youremail
entityIdNS
email (replace Phone with email)
schema.name
_xdm.context.profile
If your email address contains special symbols like +, you have to select your full email address, do a right-click and click EncodeURIComponent.
You'll then have this:
You should also verify the Header - fields of your request. Go to Headers. You'll then see this:
Key
Value
x-sandbox-name
--aepSandboxId--
[!NOTE]
You need to specify the name of the Adobe Experience Platform sandbox you're using. Your x-sandbox-name should be --aepSandboxId--.
Click the blue Send button and verify the response.
This is a very important kind of flexibility that is offered to brands. This means that any environment can send a request to Platform, using their own ID and namespace, without having to understand the complexity of multiple namespaces and IDs.
As an example:
the Call Center will request data from Platform using the namespace phone
the Loyalty System will request data from Platform using the namespace email
online applications might use the namespace ecid
The Call Center doesn't necessarily know what kind of identifier is used in the Loyalty System and the Loyalty System doesn't necessarily know what kind of identifier is used by online applications. Each individual system can use the information that they have and understand to get the information they need, when they need it.
3.3.5 Real-time Customer Profile API, Schema: Profile and ExperienceEvent
After having queried Platform's APIs successfully for Profile data, let's now do the same with ExperienceEvent data.
In Postman, locate the collection _Adobe Experience Platform Enablement.
In 1. Unified Profile Service, select the second request with the name UPS - GET Profile & EE by Entity ID & NS.
For this request, there are four required variables:
Key
Value
Definition
schema.name
_xdm.context.experienceevent
the specific schema for which you want to receive information. In this case, we're looking for data that is mapped against the ExperienceEvent schema.
relatedSchema.name
_xdm.context.profile
While we're looking for data that is mapped against the ExperienceEvent schema, we need to specify an identity for which we want to receive that data. The schema that has access to identity is the Profile-schema, so the relatedSchema here is the Profile-schema.
relatedEntityId
id
the specific customer I D
relatedEntityIdNS
namespace
the specific namespace that is applicable to the ID
So, if you want to ask Platform's APIs to give you back all Profile information for your own ecid, you will need to configure the request as follows:
Key
Value
schema.name
_xdm.context.experienceevent
relatedSchema.name
_xdm.context.profile
relatedEntityId
yourECID
relatedEntityIdNS
ecid
You should also verify the Header - fields of your request. Go to Headers. You'll then see this:
Key
Value
x-sandbox-name
--aepSandboxId--
[!NOTE]
You need to specify the name of the Adobe Experience Platform sandbox you're using. Your x-sandbox-name should be --aepSandboxId--.
Click Send to send your request to Platform.
You should get an immediate response from Platform, showing you something like this:
Below is the full response from Platform. In this example, there are eight ExperienceEvents linked to this customer's ECID. Have a look at the below to see the different variables on the request, as what you see below is the direct consequence of your configuration in Launch in previous exercises.
Also, when the X-ray panel shows ExperienceEvent information, it is using the below payload to parse and retrieve the information like Product Name (search for productName in the below payload) and Product Image URL (search for productImageUrl in the below payload).
This is currently all of the available ExperienceEvent data in Platform for this ECID.
You're not required to use the ECID to request ExperienceEvent data from Adobe Experience Platform's Real-time Profile, you can use any ID in any namespace to request this data.
