The Kameleoon AWS Lambda@Edge Starter Kit demonstrates Kameleoon experimentation and feature flags on Amazon Web Services (AWS) Lambda@Edge.

This repository is home to the Kameleoon starter kit for AWS Lambda@Edge. Kameleoon is a powerful experimentation and personalization platform for product teams that enables you to make insightful discoveries by testing the features on your roadmap. Discover more at https://kameleoon.com, or see the developer documentation.

• Getting started
  • Prerequisites
  • Set up the edge environment
  • Install the starter kit
• Use the AWS Lambda@Edge Starter Kit
• Development
  • Testing Locally
  • Commands
• Additional Resources and Concepts
  • External Data Fetching & Caching
  • Identity Management
  • AWS Lambda@Edge and Kameleoon resources

This starter kit provides quick start instructions for developers using the Kameleoon NodeJS SDK with AWS Lambda@Edge.

Make sure you have the following requirements before you get started:

1. A Kameleoon user account. Visit kameleoon.com to learn more.
2. An AWS account with Lambda@Edge access. For more information, visit the official AWS Lambda@Edge product page.

First, you'll set up a basic AWS Lambda@Edge environment. For this step, follow the official tutorial from AWS to create a simple Lambda@Edge Function.

In the tutorial, complete these sections:

1. Sign up for AWS account - If you don't have an account, please sign up for Amazon Web Services at https://aws.amazon.com.

2. Create a Cloudfront distribution - If you're not familiar with CloudFront, take a few minutes to read a short overview and learn a bit about how CloudFront caches and serves content.

3. Create a Lambda function - In this step, you create a Lambda function, starting with a blueprint template that's provided in the Lambda Console.

4. Add your Cloudfront trigger to Lambda function - Now that you have a Lambda function, configure the CloudFront trigger to run your function.

5. Verify that the function runs - Make sure that your environment is properly configured.

After your Lambda@Edge environment is prepared, install the starter kit:

1. Clone this repository to your local development environment.
2. In a terminal, navigate to the aws-lambda-edge-starter-kit/ directory.
3. Run npm install.

The Kameleoon AWS Lambda@Edge Starter Kit uses and extends the Kameleoon NodeJS SDK to provide experimentation and feature flagging on the edge.

In the src folder of the starter kit, you will find two TypeScript files:

• src/handler.ts contains sample code that initializes and caches the Kameleoon SDK and retrieves the feature flag variation.
• src/visitorCodeManager.ts file contains a custom implementation of Kameleoon Visitor Code Manager, which provides an ability to work with Kameleoon visitorCode at the edge.

You'll use these files to initialize your environment:

1. Navigate to src/handler.ts and update the SITE_CODE, CLIENT_ID, CLIENT_SECRET and FEATURE_KEY with your Kameleoon credentials and feature flag data collected on the Kameleoon Platform.

2. Review or adjust the feature flags or experiments you've configured with the Kameleoon NodeJS SDK, and hook into the lifecycle events by adding your own logic in src/handler.ts. For example, you can change headers, cookies, and more.

3. Run npm run build:lambda to bundle the source code into a dist/handler.zip file that you'll import into Lambda.

4. Upload the dist/handler.zip file into Lambda using one of these options:

   • GUI: Go to your AWS Lambda console, select the function associated with your Lambda environment, and import the dist/handler.zip file. After you upload it, there should now be a minified index.js file located inside of your Lambda function's Code Source section.
   • CLI: You can use the AWS CLI to update your AWS Lambda function programmatically. Example command:

     aws lambda update-function-code --function-name my-aws-lambda-at-edge-function --zip-file fileb://dist/handler.zip
     

5. Upload the response dist/handler.zip file into Lambda.

   Lambda Layers: If you need additional libraries, custom runtimes, or configuration files to use alongside your Lambda function, consider using Lambda Layers.

6. Provision the function with Lambda@Edge permissions and associate the function with your CloudFront distribution.

   Note: CloudFront triggers are associated with only one specific version of your Lambda function. Remember to update the CloudFront trigger assignment as needed when pushing new versions of your Lambda function. For example, you may need one function that handles receiving viewer requests (viewer request trigger) and one function that handles returning a response to the viewer (viewer response trigger).

7. Test your Lambda@Edge function. It should return a simple home page with the results of your feature flag test and User ID cookie.

   You can find details on how the starter kit works in the CloudWatch console under Logs > Log groups > /aws/lambda/<YOUR_LAMBDA_NAME>. Click your Lambda's log group to follow the entire process.

8. Adjust your lambda's configuration as needed. For example, you may need to increase your function's memory, storage, and timeout threshold to accommodate your needs.

You can now use Kameleoon's feature flagging and experimentation as desired. You can modify the cookies and headers based on experimentation results, add hooks to the Origin Request and Origin Response CloudFront triggers to perform origin redirects or dynamic asset manipulation, or add more services to the pipeline including your own logging systems, databases, CDN origins, and more. Keep in mind that Lambda@Edge has some limitations, which you can familiarize yourself with in the Edge Functions Restrictions article.

To avoid uploading your Lambda function to AWS every time you make a change, you can test your Lambda function locally using the AWS SAM runtime interface client.

1. Install the AWS SAM CLI.
2. Run npm run test:viewer_request to build the lambda and run it locally with the viewer-request event.

You can also run lambda handler using viewer-response/origin-request/origin-response events by running the related commands.

Additionally you can change the configuration of lambda by providing additional parameters to template.yaml or by modifying the template event files in the lambda folder.

The following commands are available in the starter kit:

• npm run build - Builds the TypeScript files in the src/ directory creating dist/handler.js (ignores src/examples).
• npm run build:lambda - Builds the Lambda function and creates a dist/handler.zip file.
• npm run test:viewer_request - Runs the Lambda function locally with the lambda/viewer-request.json event.
• npm run test:viewer_response - Runs the Lambda function locally with the lambda/viewer-response.json event.
• npm run test:origin_request - Runs the Lambda function locally with the lambda/origin-request.json event.
• npm run test:origin_response - Runs the Lambda function locally with the lambda/origin-response.json event.
• npm run clean - Removes the dist/ directory.

SDK configuration and collected data is stored in-memory in the Lambda function. In some cases, when the data is too large, the Lambda function may break. To address this, you can cache the data more efficiently using AWS services like S3, DynamoDB, or CloudFront.

You can find basic examples of caching SDK configuration in src/examples/configurationCache.ts and caching SDK stored data in src/examples/dataCache.ts. These basic examples store data in AWS Lambda cache for more details on working with AWS service reference official AWS documentation.

Note: Additional caching mechanisms may be available depending on your CloudFront distribution's configuration.

Out of the box, our starter kit uses a basic implementation of KameleoonVisitorCodeManager found in src/visitorCodeManager.ts. This implementation allows for basic Kameleoon Visitor Code reads and writes using lambda handler's request and response objects making the use of getVisitorCode method seamless. Alternatively you can use your own User ID or other identifier as a visitor code.

For more information about AWS Lambda@Edge and Kameleoon, see the following resources:

• Lambda - Lambda@Edge official documentation
• CloudFront - Lambda@Edge documentation
• CloudFront - Lambda@Edge Get Started
• Example Lambda Functions
• Kameleoon NodeJS SDK documentation
• Kameleoon Serverless edge compute starter kits