It's never been more important for organizations of all sizes to personalize their experiences for their customers and audiences, and AEM and Adobe Target are two stellar ways to do this.
Here's a link to a post which I coauthored to show how to use Project Firefly, our framework for building custom, cloud-native Adobe apps, to integrate AEM and Target in a separate UI to more easily achieve your personalization goals.
Showing posts with label Adobe I/O. Show all posts
Showing posts with label Adobe I/O. Show all posts
Sunday, August 23, 2020
Friday, May 8, 2020
AdobeDevBlog: Adobe I/O Architecture and Use Cases
Adobe I/O is a one-stop shop for developers, giving them everything they need to extend the capabilities of the Adobe tech ecosystem. I coauthored a post where we took a look under the hood at our I/O architecture, components, and all the dev tools and services available on I/O Runtime (Adobe's serverless platform), plus the different Adobe Experience Cloud use cases that I/O makes possible. Here's a link to Adobe's Medium Tech blog post I coauthored and below is the visual of the architecture.
Monday, January 27, 2020
Adobe I/O Events: Webhooks and The Triggers API Call
Companies around the world are continuously evolving and finding creative ways to optimize and improve the user experience across numerous platforms. The latest buzzword in that shift is Serverless Computing which is slowly shifting the narrative by allowing you to deploy abstracted code to tackle specific use cases as opposed to setting up massive a Server infrastructure. Now, I'm not saying that the latter is going away but activating specific actions is what some companies are slowly moving towards without necessarily relying on 3rd party hosted solutions. One such use case where Serverless can help is Triggers which I wrote about last year.
I also gave an overview of Adobe I/O where I wrote about the four I/O components and I/O Runtime is at the helm of it all. In this article, I'm going to walk through the application of application of Adobe I/O Events in Triggers. I'm also going to cover how to setup webhooks on your machine (Mac in my case) and leverage a script the Adobe development team wrote to use your machine to "listen" for incoming Triggers. So let's get started.
The steps till #7 in this diagram are almost the same as any regular Triggers lifecycle which I covered in my previous post so here, I'll cover everything from step 8 onwards. If some steps are not clear, don't worry as I will cover these in more detail later in the post. So, let's walk through these in more detail:
8a - A user subscribes to the Triggers API using Runtime by creating a webhook. A prerequisite is to subscribe to the Triggers API which is done in the Admin console (covered later).
8b - The webhook is registered in the Adobe Admin console which is validated by the Event Gateway.
9a - The Analytics Trigger is sent to I/O Events as soon as the trigger is executed (E.g. cart abandonment, some page is viewed etc.).
9b - I/O Events sends the Trigger JSON payload to the client which is collected at some endpoint leveraging Runtime via a POST request.
9c - A Runtime action is invoked as a custom event to send the JSON payload to a 3rd party Email Service Provider (ESP). Please note Adobe Campaign will automatically receive the JSON payload (step 7).
10 - Runtime action is invoked to query data and receive the output.
11 - This output is sent to an SFTP location to Adobe Campaign or other ESPs via another action.
12- ESP sends an email or SMS tied to the trigger payload and conditional logic.
13 - User clicks on the email and is routed back to the site.
Download ngrok from https://ngrok.com/ and run the ngrok application from your Terminal or Command Prompt pointing to the folder where the application is located. In my case, it's located in the /openwhisk folder and I'm creating an ngrok URL tied to my localhost on port 3000 by executing the command ./ngrok http 3000. I'll cover why I chose 3000 later.
Once executed, you'll get the public facing URL for your localhost which is https://c926b37a.ngrok.io/ in my case. Please note that this URL is only public facing for 8 hours but I believe there's a paid version to make reserved URLs.
In this section, I will execute some code written by the Adobe I/O Events development team (A big Thanks for them!) that I retrieved from the Adobe Github page which has additional instructions on how to set this up as well but the main thing is to install this package on your machine. The command to run is npm start (Node.js) once you've installed the package to run the app.js file.
Once it executes, it publishes an HTML page on port 3000 which allows us to create our webhook. Note that this is the same port on which I created my ngrok URL. On this page, I enter a path (trigger) which creates a webhook as https://c926b37a.ngrok.io/webhook/trigger that will "listen" for any incoming triggers.
The first step is to create an integration with Analytics Triggers in the Adobe I/O admin interface. Follow these steps to create it.
Once the integration is complete, the next step is to click on the "Events" tab of your integration and register & test your newly created webhook. Note that I'm registering the same webhook created in the previous step which is https://c926b37a.ngrok.io/webhook/trigger.
Once you save it, a challenge will be sent as a GET request to this webhook to check if it's active.
If it's live, then you'll see the "Active" status in the admin console page which means your webhook is now ready to listen for Triggers.
Aside from the Triggers UI, I can also see five Trigger events posted on the app.js page actively listening for the events. Based on my test, it took the between 20-30 seconds for me to receive the webhook (see below) and I got 5 triggers (POST requests).
In this step, we will integrate our webhook with Slack to send a Trigger response to a Slack channel when an event occurs. You can do that by going here which is the regular process. In my case, I went here and added this app to my Slack workspace and channel called #trigger-channel.
Once you complete the integration, you'll receive your Slack Webhook URL which looks like this: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
Once the integration is complete, you can send a POST request to the hook and post a custom message like I did via Postman.
Once it's done, you'll see a bunch of messages stating the the integration is setup including a "Hello World" message which I sent.
Next, I'll show you how to enable Slack to receive your Triggers webhook.
Modify the app.js file and update your webhook URL and channel name.
Next, we'll modify the Triggers payload to customize what we want to send to our Slack channel. In my case, I want to display my ECID and URL which I've slightly modified in the script written by the Adobe I/O team.
Finally, we can see that we got 5 Trigger responses in our Slack channel as well like we saw in the Triggers UI and the ngrok "listening" page. Again, not sure if this a good use case for Slack but you can use the model for other use cases which are more pertinent.
So, that was it! Hope you found this helpful for your own use case on how to use I/O Events. Are you using Adobe I/O in any form today?
I also gave an overview of Adobe I/O where I wrote about the four I/O components and I/O Runtime is at the helm of it all. In this article, I'm going to walk through the application of application of Adobe I/O Events in Triggers. I'm also going to cover how to setup webhooks on your machine (Mac in my case) and leverage a script the Adobe development team wrote to use your machine to "listen" for incoming Triggers. So let's get started.
Triggers Architecture with Adobe I/O
Below is a high level architecture diagram I created to show how the Triggers API would interact with the various Adobe I/O components primarily Runtime and Events. Please note that this is a subset of what all is possible with I/O and an overall Adobe I/O architecture diagram is still in the works which will show the complete picture.
The steps till #7 in this diagram are almost the same as any regular Triggers lifecycle which I covered in my previous post so here, I'll cover everything from step 8 onwards. If some steps are not clear, don't worry as I will cover these in more detail later in the post. So, let's walk through these in more detail:
8a - A user subscribes to the Triggers API using Runtime by creating a webhook. A prerequisite is to subscribe to the Triggers API which is done in the Admin console (covered later).
8b - The webhook is registered in the Adobe Admin console which is validated by the Event Gateway.
9a - The Analytics Trigger is sent to I/O Events as soon as the trigger is executed (E.g. cart abandonment, some page is viewed etc.).
9b - I/O Events sends the Trigger JSON payload to the client which is collected at some endpoint leveraging Runtime via a POST request.
9c - A Runtime action is invoked as a custom event to send the JSON payload to a 3rd party Email Service Provider (ESP). Please note Adobe Campaign will automatically receive the JSON payload (step 7).
10 - Runtime action is invoked to query data and receive the output.
11 - This output is sent to an SFTP location to Adobe Campaign or other ESPs via another action.
12- ESP sends an email or SMS tied to the trigger payload and conditional logic.
13 - User clicks on the email and is routed back to the site.
Listen for I/O Events Via a Webhook
In this section, I'll cover some steps on how to setup a webhook using ngrok which is a tunneling software that allows you to convert your local site URL into a public facing URL. Please note that I'm not using the Runtime AIO CLI to do this but I have it installed on my machine and the instructions to install it can be found here.
Setup ngrok
Download ngrok from https://ngrok.com/ and run the ngrok application from your Terminal or Command Prompt pointing to the folder where the application is located. In my case, it's located in the /openwhisk folder and I'm creating an ngrok URL tied to my localhost on port 3000 by executing the command ./ngrok http 3000. I'll cover why I chose 3000 later.
Once executed, you'll get the public facing URL for your localhost which is https://c926b37a.ngrok.io/ in my case. Please note that this URL is only public facing for 8 hours but I believe there's a paid version to make reserved URLs.
Create a Webhook "Listening" Server
Once it executes, it publishes an HTML page on port 3000 which allows us to create our webhook. Note that this is the same port on which I created my ngrok URL. On this page, I enter a path (trigger) which creates a webhook as https://c926b37a.ngrok.io/webhook/trigger that will "listen" for any incoming triggers.
Register Webhook in Admin Console
Once the integration is complete, the next step is to click on the "Events" tab of your integration and register & test your newly created webhook. Note that I'm registering the same webhook created in the previous step which is https://c926b37a.ngrok.io/webhook/trigger.
Once you save it, a challenge will be sent as a GET request to this webhook to check if it's active.
If it's live, then you'll see the "Active" status in the admin console page which means your webhook is now ready to listen for Triggers.
Create and Test Your Trigger
For the purpose of this post, I've created a very simple Trigger Action to fire when a user visits my homepage called "sandbox-home" and visited my page a few times.
Aside from the Triggers UI, I can also see five Trigger events posted on the app.js page actively listening for the events. Based on my test, it took the between 20-30 seconds for me to receive the webhook (see below) and I got 5 triggers (POST requests).
Parse the Trigger POST Response
Finally, you can parse the trigger response by expanding the POST request. In the JSON response, we can see that there are two main components of the call where the first one has information about the timestamp, IMS org among others and the second one is the actual analyticsHitSummary payload that contains all the "enriched" data from Adobe Analytics. Please note that a valid use case for this would be to send this to a 3rd party Email Service Provider given that Adobe Campaign receives it automatically. Please note that the customer ID (used to link ACS with a customer ID) captured on your site needs to be sent in an eVar as part of the Payload.
BONUS: Send a Slack Message When a Trigger Occurs
Now, this section is just to show how to send a message to a Slack channel when a Trigger fires. Please note that this is probably not a good use case for Slack given the frequency of Triggers so some better use cases will be server maintenance notifications, code publishing notifications, new members added or removed, fraud detection among many others. I'll just use the Triggers API to show how it works:
Enable Incoming Webhook for Slack
In this step, we will integrate our webhook with Slack to send a Trigger response to a Slack channel when an event occurs. You can do that by going here which is the regular process. In my case, I went here and added this app to my Slack workspace and channel called #trigger-channel.
Once you complete the integration, you'll receive your Slack Webhook URL which looks like this: https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX
Once the integration is complete, you can send a POST request to the hook and post a custom message like I did via Postman.
Once it's done, you'll see a bunch of messages stating the the integration is setup including a "Hello World" message which I sent.
Modify Code In app.js
Modify the app.js file and update your webhook URL and channel name.
Next, we'll modify the Triggers payload to customize what we want to send to our Slack channel. In my case, I want to display my ECID and URL which I've slightly modified in the script written by the Adobe I/O team.
Monitor Triggers in Slack
Finally, we can see that we got 5 Trigger responses in our Slack channel as well like we saw in the Triggers UI and the ngrok "listening" page. Again, not sure if this a good use case for Slack but you can use the model for other use cases which are more pertinent.
So, that was it! Hope you found this helpful for your own use case on how to use I/O Events. Are you using Adobe I/O in any form today?
Wednesday, December 25, 2019
Overview of Adobe I/O
Our customers are always looking for various ways to access and extend the capabilities of our solutions and APIs are a natural way to provide them with additional capabilities that the UI may not provide. Adobe I/O allows developers to find documentation and tools to integrate with the Experience, Creative, and Document Clouds in a streamlined manner. In addition, it allows developers to add more functionality to Adobe solutions and customize them to tailor experiences for their customers.
The Adobe I/O platform has four primary components which I'll cover at a high level. I wrote about this in more detail on Medium where I coauthored a post on the architecture of Adobe I/O and its uses cases. This post also shows how each of these components interact with each other and the Experience Cloud solutions.
As a continuation to my previous post on accessing Adobe APIs using Postman, here's another example of how to access a User Management API to get a list of all products a user is subscribed to which can allow you to retrieve this information without logging into the Admin console UI. Please note that you need to access the Adobe Developer console to create an integration with the User Management API.
The first step is to get an access token using the JWT token created in the Developer console.
Call the API to get user information by using the Bearer token generated in the previous step and getting a list of all groups a user has subscribed to. There's another API which allows you to get a list of all users and their groups tied to a particular Adobe IMS org.
I'll update this post once I've created a diagram to show how each of the I/O components talk to each other. So, how do you use Adobe I/O in your organization?
The Adobe I/O platform has four primary components which I'll cover at a high level. I wrote about this in more detail on Medium where I coauthored a post on the architecture of Adobe I/O and its uses cases. This post also shows how each of these components interact with each other and the Experience Cloud solutions.
- Adobe Developer Console (Tool): The Adobe Developer console provides you with a UI to access APIs across the three Adobe clouds as shown below. Developers can create integrations with each of these solutions primarily via three authentication methods (Api key, OAuth and JWT) to access APIs for solutions such as Adobe Analytics, Audience Manager, Campaign etc. The previous article I wrote shows how to access these APIs using JWT via Postman.
- Adobe I/O Gateway (Service): Adobe I/O Gateway is the infrastructure that sits in front of Adobe services and exposes the APIs. It does things like throttling and logging, routing and load balancing, authentication and security, whitelisting, validating API keys, tokens among others. There isn't much documentation available and it's not an actual product or UI that clients have access to.
- Adobe I/O Events (Service): Adobe I/O Events allow you to programmatically deliver targeted, expedited, and personalized experiences based on user behavior. I/O Developers can subscribe to webhooks and can define what they want to be notified for whenever certain events occur. An example is triggers which allows you to send an email if a user abandons an eCommerce cart or update your 3rd party CRM system based on any action performed on the website. Some other examples of Events are as follows:
- When an AEM asset is uploaded or updated, republish the page with the newly updated asset
- If Adobe Analytics traffic spikes, create a segment
- Get a cadence and order of occurrence of events via the Journaling API
- Some other use cases around the creative and document clouds is outlined here.
- Adobe I/O Runtime (Service): Adobe I/O Runtime is a powerful and serverless way for developers to extend the capabilities of Adobe Experience Cloud solutions with no server management required. It allows developers to transform their code into applications by writing and deploying code on top of the Adobe Experience Cloud stack. It is built on top of Apache OpenWhisk, which is an open source project that is very flexible and allows you to code in many programming languages such as Node.js, JavaScript, Swift, Python, PHP, Java to name a few. The great thing about is that you don't have to setup any servers or software to run your code. Some use cases for I/O Runtime are as follows:
- Write code to perform ETL on records stored in a 3rd party CRM system and send these to Adobe Audience Manager or Campaign
- Allows you to open an internal ticket if a negative review is added
- This article covers a very pertinent use case for integrating Adobe Campaign Classic with Adobe Experience Platform
- Some other Runtime related use cases are outlined here.
The first step is to get an access token using the JWT token created in the Developer console.
Call the API to get user information by using the Bearer token generated in the previous step and getting a list of all groups a user has subscribed to. There's another API which allows you to get a list of all users and their groups tied to a particular Adobe IMS org.
I'll update this post once I've created a diagram to show how each of the I/O components talk to each other. So, how do you use Adobe I/O in your organization?
Sunday, May 26, 2019
Access Adobe APIs Using Postman
APIs (Application Programming Interface) facilitate the transfer of information between two systems and are leveraged in a magnitude of industries today ranging from Travel to Retail. Adobe offers open source APIs in its solutions across the Document, Creative and Experience Clouds. Major companies leverage APIs to allow users to do the following:
In this post, I will cover how to leverage Adobe APIs for Launch by Adobe and Audience Manager but these APIs are also available to use across some other Experience Cloud solutions such as Adobe Analytics and Adobe Target via Adobe I/O. We won't go into the basics of how to create integrations as there's a lot of documentation available on it but we'll cover the steps on how to call the APIs using authentication tokens in Postman. Please note that Audience Manager is not part of Adobe I/O yet and we'll specifically cover REST APIs to work with elements within the AAM UI. Let's jump right in!
The next step is to enter the AAM UI credentials as shown below to generate the access token that will be used to access additional APIs.
We'll now create a simple trait by sending a POST request to https://api.demdex.com/v1/traits/. The only additional attributes we're adding is the Folder ID and the Data Source ID which we can get from the AAM UI. The result is the following as shown in the screenshots below.
Please note that the API doesn't have a way to create traits in bulk so you can leverage BAAAM to do so which is a custom solution.
This is the final request in this post to get details about traits but you can retrieve data for segments, destinations, data sources etc. We send a GET request to https://api.demdex.com/v1/traits/ to retrieve all traits within our AAM instance. In our case, we can see that the trait we just created can be accessed using this method and you can export this JSON output and perform additional searches.
- Share content on Social Media (Facebook)
- Retrieve flight information (Alaska Airlines)
- Real-time access to item price and availability (Amazon)
- Access maps using GPS (Google Maps)
- Tracking information on shipments (FedEx)
- Server Side Analytics Implementation (Adobe)
In this post, I will cover how to leverage Adobe APIs for Launch by Adobe and Audience Manager but these APIs are also available to use across some other Experience Cloud solutions such as Adobe Analytics and Adobe Target via Adobe I/O. We won't go into the basics of how to create integrations as there's a lot of documentation available on it but we'll cover the steps on how to call the APIs using authentication tokens in Postman. Please note that Audience Manager is not part of Adobe I/O yet and we'll specifically cover REST APIs to work with elements within the AAM UI. Let's jump right in!
Launch By Adobe APIs
The first solution we will cover is Launch where we'll create a property and you can use this format to create , data elements, rules, environments etc. The first step is to go to the Adobe I/O console which shows you all the integrations setup for your experience cloud org. In this case, we've created an integration with Launch APIs using Adobe I/O.
Make sure you either select the Developer role or the Admin role (while creating the integration) in order to create properties. I had chosen Approver as listed in the instructions in our documentation which walks us through how to create an integration but that didn't let me create a Launch property.
We'll now create a new Launch property by making a POST request to https://reactor.adobe.io/companies/:company_id/properties as covered here. We can also create Launch rules, data elements, environments etc using this method. Below is how we can make this call.
We'll now cover how make a GET request to https://reactor.adobe.io/properties/:id to fetch the details of the Launch property we just created by entering the property ID (starting with PR) which you can get from the response you get when you created the property. We're going to leverage some mandatory attributes defined here as shown below (The {{property}} value stores the property ID). You can use this to get access to a lot of information such as name, creation timestamp, domains etc. We can also fetch the details of data elements, rules and extensions among other things.
The following screen will show you your API credentials which you'll need to access the API and the ones which is required is API Key and Client Secret. We'll also need the Org ID that needs to be sent as an additional attribute in one of the requests we'll make in one of the API calls covered later in this post.
The next step is to generate the JWT (JSON Web Token) which will be used to authenticate and access the Launch APIs. The Private Key is generated as part of the public certificate (CRT file) creation process outlined in the Launch documentation. Please note that during the creation of the certification, an additional file called private.key is generated which contains this information.
The next step is to use the generated JWT to create a Launch token that will be used to access Adobe APIs.
We need to now copy the generated JWT in Postman to create a new access token (valid for 24 hours) but before that, I want to share with you a tip which my colleague Gil Jimenez shared with me. The tip is to create global variables in Postman to store sensitive values that you'll need to access over and over again. You can do that by clicking on the Environment icon as shown below. The other thing you can do is to save these API calls as collections in the form of separate folders as shown below in the left section.
Generate a Launch Access Token
The next step is to generate an access token using the client_id, client_secret and jwt_token parameters by making a POST request to https://ims-na1.adobelogin.com/ims/exchange/jwt/ as explained here. Note how we're using the global variables to store sensitive information and accessing it in the call. We need copy this access token and store it. In our case, we're storing it in a separate variable calls access-token which is different that the jwt-token we need to create it.
Make a POST Request to Create a Property
We'll now create a new Launch property by making a POST request to https://reactor.adobe.io/companies/:company_id/properties as covered here. We can also create Launch rules, data elements, environments etc using this method. Below is how we can make this call.
Once we press send, we successfully (if everything goes well) create a Launch property as shown below. So using APIs, developers can literally do everything in Launch without having to login to Launch. These APIs are open source and super powerful!
Make a GET Request for a Property
We'll now cover how make a GET request to https://reactor.adobe.io/properties/:id to fetch the details of the Launch property we just created by entering the property ID (starting with PR) which you can get from the response you get when you created the property. We're going to leverage some mandatory attributes defined here as shown below (The {{property}} value stores the property ID). You can use this to get access to a lot of information such as name, creation timestamp, domains etc. We can also fetch the details of data elements, rules and extensions among other things.
Adobe Audience Manager REST APIs
We'll now cover how to make GET and POST requests for AAM using Postman to access REST APIs (centered around the AAM UI) which allow you to perform some basic functions without logging into the AAM UI. Please note that there's another set of APIs called DCS APIs (send data to AAM) which I'll save for a future post.
Generate an AAM Access Token
As I mentioned earlier, the AAM APIs are not yet part of Adobe I/O so in order to access the REST APIs, we need the following credentials to access the APIs:
- AAM API user name (AAM Admin UI)- Adobe consultant can provide this
- AAM API password (AAM Admin UI)- Adobe consultant can provide this
- AAM UI Username (bank.demdex.com login)
- AAM UI Password (bank.demdex.com login)
Once you have these credentials, we can leverage Postman to get the access token which is only valid for a few minutes. Here we enter the AAM API and password using Basic Auth and send a POST request to https://api.demdex.com/oauth/token.
The next step is to enter the AAM UI credentials as shown below to generate the access token that will be used to access additional APIs.
Make a POST Request to Create a Folder
We can access all AAM APIs in the Swagger API portal. The first thing we want to create is a folder by sending a POST call to https://api.demdex.com/v1/folders/traits/ using the Bearer Token auth type as shown below. The folder is "REST API Test" and it will be placed under the root "All Traits" folder.
Once the call goes through successfully, we should see the following message and the folder should show up in the AAM UI immediately.
Make a POST Request to Create a Trait
We'll now create a simple trait by sending a POST request to https://api.demdex.com/v1/traits/. The only additional attributes we're adding is the Folder ID and the Data Source ID which we can get from the AAM UI. The result is the following as shown in the screenshots below.
Please note that the API doesn't have a way to create traits in bulk so you can leverage BAAAM to do so which is a custom solution.
Make a GET Request to Retrieve all Traits
This is the final request in this post to get details about traits but you can retrieve data for segments, destinations, data sources etc. We send a GET request to https://api.demdex.com/v1/traits/ to retrieve all traits within our AAM instance. In our case, we can see that the trait we just created can be accessed using this method and you can export this JSON output and perform additional searches.
So, this was just a small glimpse into what's possible via APIs where we're able to perform the same tasks that we usually do in the Adobe solution specific UIs. This also shows us that almost everything that happens in the UI is driven by APIs so in a way we took a look under the hood of Launch and Audience Manager. Hope you found this post useful.
Subscribe to:
Posts (Atom)