Personalization is the process of tailoring a product or a service on the basis of your audience preferences. You implement personalization by customizing your website or its content (text or images) based on your users' behavior and interactions.
Dynamic Yield is a popular AI-powered personalization platform that helps businesses to enhance the digital customer experience through machine learning, predictive algorithms, auto-optimization, and recommendations.
In this guide, we will discuss how we can implement Dynamic Yield on a Contentstack-powered website.
To understand how this works, we have created an example app using Express.js. The code can be downloaded from our GitHub repository or you can clone our repository. The downloaded project has sample content in a zip file named "content.zip" inside the "stack-content" folder which you need to import into your stack. We will describe below how to import the content using the Contentstack CLI.
The solution will take the content of the entry from the Home content type in a JSON format and using a webhook send it to an AWS lambda function that will convert the content of this entry to a CSV file and upload it in an S3 bucket. By using the content of this CSV file, we will create variations in Dynamic Yield and implement them on our Home page to see what personalized content works best.
Steps for Execution
- Download the sample code
- Import Content using CLI
- Create a Delivery token
- Create an AWS S3 bucket
- Create an AWS lambda function
- Set up an API Gateway
- Create a webhook in Contentstack
- Add the data feed source in Dynamic Yield
- Create a template for your variations in Dynamic Yield
- Create an API custom campaign using the variation feed
- Get variation using Dynamic Yield's API and start the app
Download the Sample Code
For this exercise, you will use two sample code files:
- One for the AWS Lambda function (file name index.zip which is inside the lambda-function folder).
- Another one for our sample website content that we have built for this exercise.
You will need to unzip the content.zip file, which is inside the stack-content folder. Make a note of the path of the unzipped content folder as you will need this path in the next step.
Import Content using CLI
To help you understand how Dynamic Yield works with Contentstack, we have created a sample implementation. We have also created the content type schema and its entry in Contentstack. You simply need to import them to your Stack and we will use them in the sample application.
To do this, you can use Contentstack command-line interface (CLI) and use the following steps:
- Install the Contentstack CLI:
npm install -g @contentstack/cli
- Authenticate yourself with CLI:
- Add a Management token to the session:
Note: To add a management token to the CLI session, make sure you have first generated that management token for your stack.
- Import the content types, assets, and entries:
csdx cm:import -a <management_token_alias> -l <master_lang_of_stack> -d “<path>”
- -a: Name/alias of the management token added in the session
- -l: Code of the master language of your stack
- -d: Path of the “content” folder downloaded in the previous step
Example: csdx cm:import -a mgmt -l "en-us" -d "/Code/DY-Sample-App/stack-content/content"
where mgmt is the alias of the Management token and the content folder contains folders for entries, assets, content_types, environments, and locales.
Create a Delivery Token
Once you have all the content in place, you need to generate a delivery token for the imported environment(s) to fetch the entry. If you don’t see your environment, refresh your browser.
Now that our essentials are ready, let's move ahead and set up S3 and AWS Lambda.
Create an S3 Bucket
We need an S3 bucket to store the CSV file of our entry. To do this, perform the following steps:
- Log in to your AWS Management Console and, select S3 from the Services list.
- On the Amazon S3 page, click on Create bucket
- On the Create Bucket page, provide a Bucket name, and uncheck the Block all public access option as shown below:
- Finally, click on the Create bucket button. Make a note of your “S3 bucket name” as you will need it in the next step.
Create an AWS Lambda Function
Perform the following steps to set up the AWS lambda function:
- From the Services list, select Lambda.
- Click on the Create function button and then the Author from scratch option.
- Provide a name to your lambda function, choose Node.js 12.x as your run-time language, and click on the Create function button.
- AWS Lambda offers an inline code editor. You can write your lambda code here or upload the code. For our example, we have provided the sample code which you downloaded in step 1.
Upload the index.zip file, located inside the lambda-function folder, on Lambda by selecting the Upload a .zip file option from the Actions dropdown of the Function code window.
Note: Make sure the Handler, located in the Basic settings card, is set to index.handler.After uploading the zip file to the Lambda function, you will see the following screen:
Note: The uploaded code file is large and therefore it will not be seen in the code editor. But the zip file is successfully uploaded to your Lambda function and you can proceed to the next step.
- Add the following Environment variables to the function:
ACCESS_KEY: Access key of your AWS account
SECRET_ACCESS_KEY: Secret access key of your AWS account
BUCKET_NAME: Name of your S3 bucket
Additional resource: Learn how to generate the Access and Secret access key in AWS in this guide.
Now that your AWS lambda function is ready, let's create the API gateway to get the URL where our webhook will issue notifications.
Set up an API Gateway
For your Lambda function to be accessible publicly, you need to configure the AWS API Gateway using your function as the backend for the API as shown below:
- Navigate to the Lambda service, and click on your Lambda function that you just created in the above step.
- Click on + Add trigger as shown below:
- In the Trigger configuration drop-down, select API Gateway.
- In the API drop-down, select Create an API, and choose the HTTP API template.
- Under the Security drop-down, select Open, and click on Add (at the bottom) to save your settings.
- After performing the above steps, you'll get an API endpoint URL that you can use while configuring the webhook in the next step.
Create a Webhook in Contentstack
We will now create a webhook that will invoke our Lambda Function. Follow the steps below:
- Log in to your Contentstack account, go to your stack, and click on the Settings gear icon.
- Then, click on Webhooks. On the Webhook page, click on + New Webhook.
- On the Create Webhook page, fill up the Name field. In the URL to notify field, enter the URL (API endpoint URL) that you generated in the previous step.
- Scroll down to the When section for creating a trigger for the webhook as shown below:
- Ensure the Enable Webhook checkbox is selected and click on Save to save your Webhook settings.
- After the successful creation of the webhook, publish the Homepage entry on the “development” environment. This publishing action invokes the lambda function that takes the variations JSON response, converts it into a CSV file, and uploads it on your S3 bucket.
- Visit your S3 bucket and you can now see the variations.csv file in the bucket. Note down the URL of this file as you will need it in the next steps.
Add the Data Feed Source in Dynamic Yield
Now create a Data Feed that connects with the data, present in the variations.csv file, by performing the following steps:
- Go to your Dynamic Yield admin portal, then Assets, and then select Data feeds.
- Click on New Feed or New (if you have already created one), and select Variation Feed.
- Give an appropriate Name and paste the URL of the variations.csv file, located in your S3 bucket, in Feed Source.
- Expand the Advanced Settings tab and select the Synchronization period to define how often you want to synchronize the feed.
- Click Preview to view some of the feed data and verify the content.
- Verify that the Unique Key and Variation Name Key are mapped to the column that contains the variation name, for example, “title.”
- Click on Save & Activate.
Create a Template for your Variations
Next, we will create a template that will be used for each of our variations. To do this, follow the steps given below:
- Go to Assets and then select Templates.
- Click on New, provide a suitable Name, and in the Template Type drop-down, choose the Custom API Campaign.
- Click on Next and in the JSON tab, add the following:
- Click on Save.
With these steps, we have added templates for our variations. Let's now move ahead with creating an API Custom Campaign.
Create an API Custom Campaign Using the Variation Feed
To do this, follow the steps given below:
- Go to API Campaigns, select Add New, and click on Custom.
- Provide a suitable Name and it will generate the API Selector Name. This selector is needed in API calls to the campaign.
Note: Make a note of the API Selector Name as you will need it while configuring the sample app.
- Click on Next. Configure the targeting for your experience as per requirements and click on Next.
- On the following Variations screen, click on syncing it with a Data Feed and select your Template.
- On the Source screen, select the Data feed source (created in Step 8), map the Data Feed Source columns with your Template Variable, and click on Next.
Note: If the Data feed source does not appear in the list, refresh the page for it to get loaded in the list.
- On the Filter Data Feed screen, click Sync Variations.
- Now, on the Variations screen, click on the “Settings” gear icon:
- Set Variations Stickiness as Not sticky, and click on Done:
- Finally, click on Save Experience, and then Publish it.
Get Variation using Dynamic Yield's API and Start the App
- First, you will need to create an API key. To do so go to Settings, then API Keys, and click on New Key.
- Enter a key Name and select Source as Server-side.
- In the ACL section, select the Personalization checkbox and click on Save.
- In the Dynamic Yield Sample app downloaded at the beginning of the tutorial, open the .env file and add the Dynamic Yield's API Key, Dynamic Yield Host, and your stack credentials (stack API key, the delivery token of the publishing environment, and the environment name).
Note: The value for the DY_HOST variable in the above code is the hostname of Dynamic Yield. It can either be North America, EU or Azure NA depending on the region where it is hosted. Refer to the Choosing Variations and Pageviews section on their guide for more details.
- Open the routes/home.js file and assign the “API Selector Name” to the selector variable:
- Now open your command prompt, and move inside the project root directory. Then, install the required dependencies by running the following command:
- Now staying in your project's root directory start the app on port 4000 using the following command:
Open the browser, hit the localhost at port 4000, reload the URL, and you'll see banner variations on your home page.
Additional Resources: You can implement personalization for your Contentstack-powered website using Optimizely too. To do so, refer to the Personalization using Optimizely guide.