Docs: Polish Readme and add examples

.gitignore

@@ -38,3 +38,6 @@ terraform.rc
 
 # Ignore IDE
 .idea/
+
+# Ignore Terraform locks in examples folder
+examples/**/*.lock.hcl

README.md

@@ -2,7 +2,7 @@
   <a href="https://fingerprint.com">
     <picture>
      <source media="(prefers-color-scheme: dark)" srcset="https://fingerprintjs.github.io/home/resources/logo_light.svg" />
-     <source media="(prefers-color-scheme: light)" srcset=https://fingerprintjs.github.io/home/resources/logo_dark.svg" />
+     <source media="(prefers-color-scheme: light)" srcset="https://fingerprintjs.github.io/home/resources/logo_dark.svg" />
      <img src="https://fingerprintjs.github.io/home/resources/logo_dark.svg" alt="Fingerprint logo" width="312px" />
    </picture>
   </a>
@@ -14,148 +14,54 @@
 <a href="https://discord.gg/39EpE2neBg"><img src="https://img.shields.io/discord/852099967190433792?style=logo&label=Discord&logo=Discord&logoColor=white" alt="Discord server"></a>
 </p>
 
-> **Warning**
-> This project is in the Private Beta phase. For more information, reach out
-> to [[email protected]](mailto:[email protected]).
-
-## How to Install
-
-### Using a new CloudFront distribution
-
-1. Create a new directory `mkdir fingerprint_integration` and go inside `cd fingerprint_integration`
-2. Create a file `touch fingerprint.tf` and add below content, do not forget to replace
-   placeholders (`AGENT_DOWNLOAD_PATH_HERE`, `RESULT_PATH_HERE`, `PROXY_SECRET_HERE`):
-     ```terraform
-     module "fingerprint_cloudfront_integration" {
-       source = "[email protected]:necipallef/terraform-module-proxy-lambda.git/?ref=v0.7.1"
-     
-       fpjs_agent_download_path = "AGENT_DOWNLOAD_PATH_HERE"
-       fpjs_get_result_path     = "RESULT_PATH_HERE"
-       fpjs_shared_secret   = "PROXY_SECRET_HERE"
-     }
-     ```
-3. Create a file called `cloudfront_distribution.tf` and add below content (feel free to make any changes that makes
-   sense for your setup):
-   ```terraform
-
-    resource "aws_cloudfront_distribution" "fpjs_cloudfront_distribution" {
-      comment = "Fingerprint distribution (created via Terraform)"
-    
-      origin {
-        domain_name = module.fingerprint_cloudfront_integration.fpjs_origin_name
-        origin_id   = module.fingerprint_cloudfront_integration.fpjs_origin_id
-        custom_origin_config {
-          origin_protocol_policy = "https-only"
-          http_port              = 80
-          https_port             = 443
-          origin_ssl_protocols   = ["TLSv1.2"]
-        }
-        custom_header {
-          name  = "FPJS_SECRET_NAME"
-          value = module.fingerprint_cloudfront_integration.fpjs_secret_manager_arn
-        }
-      }
-    
-      enabled = true
-    
-      http_version = "http1.1"
-    
-      price_class = "PriceClass_100"
-    
-      default_cache_behavior {
-        allowed_methods          = ["GET", "HEAD", "OPTIONS", "PUT", "POST", "PATCH", "DELETE"]
-        cached_methods           = ["GET", "HEAD"]
-        cache_policy_id          = module.fingerprint_cloudfront_integration.fpjs_cache_policy_id
-        origin_request_policy_id = module.fingerprint_cloudfront_integration.fpjs_origin_request_policy_id
-        target_origin_id         = module.fingerprint_cloudfront_integration.fpjs_origin_id
-        viewer_protocol_policy   = "https-only"
-        compress                 = true
-    
-        lambda_function_association {
-          event_type   = "origin-request"
-          lambda_arn   = module.fingerprint_cloudfront_integration.fpjs_proxy_lambda_arn
-          include_body = true
-        }
-      }
-    
-      viewer_certificate {
-        cloudfront_default_certificate = true
-      }
-    
-      restrictions {
-        geo_restriction {
-          restriction_type = "none"
-        }
-      }
-    }
-   ```
-   If you wish to connect a custom domain for first-party benefits, consider changing `viewer_certificate` field
-   accordingly. Refer
-   to [official documentation](https://registry.terraform.io/providers/hashicorp/aws/latest/docs/resources/cloudfront_distribution)
-   by HashiCorp for further customization.
-4. Run `terraform init`
-5. Run `terraform plan`, if all looks good run `terraform apply`
-
-### Using existing CloudFront distribution
-
-1. Create a file called `fingerprint.tf` and add below content, do not forget to replace
-   placeholders (`AGENT_DOWNLOAD_PATH_HERE`, `RESULT_PATH_HERE`, `PROXY_SECRET_HERE`):
-    ```terraform
-    module "fingerprint_cloudfront_integration" {
-        source = "[email protected]:necipallef/terraform-module-proxy-lambda.git/?ref=v0.7.1"
-
-        fpjs_agent_download_path = "AGENT_DOWNLOAD_PATH_HERE"
-        fpjs_get_result_path     = "RESULT_PATH_HERE"
-        fpjs_shared_secret   = "PROXY_SECRET_HERE"
-    }
-    ```
-2. Go to your CloudFront distribution block and add below content, do not forget to replace
-   placeholders (`YOUR_INTEGRATION_PATH_HERE`):
-    ```terraform
-    resource "aws_cloudfront_distribution" "cloudfront_dist" {
-      // more code here
-    
-      #region fingerprint start
-    
-      origin {
-        domain_name = module.fingerprint_cloudfront_integration.fpjs_origin_name
-        origin_id   = module.fingerprint_cloudfront_integration.fpjs_origin_id
-        custom_origin_config {
-          origin_protocol_policy = "https-only"
-          http_port              = 80
-          https_port             = 443
-          origin_ssl_protocols   = ["TLSv1.2"]
-        }
-        custom_header {
-          name  = "FPJS_SECRET_NAME"
-          value = module.fingerprint_cloudfront_integration.fpjs_secret_manager_arn
-        }
-      }
-    
-      ordered_cache_behavior {
-        path_pattern = "YOUR_INTEGRATION_PATH_HERE/*"
-    
-        allowed_methods          = ["GET", "HEAD", "OPTIONS", "PUT", "POST", "PATCH", "DELETE"]
-        cached_methods           = ["GET", "HEAD"]
-        cache_policy_id          = module.fingerprint_cloudfront_integration.fpjs_cache_policy_id
-        origin_request_policy_id = module.fingerprint_cloudfront_integration.fpjs_origin_request_policy_id
-        target_origin_id         = module.fingerprint_cloudfront_integration.fpjs_origin_id
-        viewer_protocol_policy   = "https-only"
-        compress                 = true
-    
-        lambda_function_association {
-          event_type   = "origin-request"
-          lambda_arn   = module.fingerprint_cloudfront_integration.fpjs_proxy_lambda_arn
-          include_body = true
-        }
-      }
-    
-      #endregion
-    
-      // more code here
-    }
-    ```
-3. Run `terraform plan`, if all looks good run `terraform apply`
-
-> [!NOTE]
-> If your project doesn't use `hashicorp/random` module, then you will need to run `terraform init -upgrade`.
+# Fingerprint Pro CloudFront Integration (Terraform module)
+
+[Fingerprint](https://fingerprint.com/) is a device intelligence platform offering 99.5% accurate visitor identification.
+
+Fingerprint Pro CloudFront Integration is responsible for
+
+- Proxying download requests of the latest Fingerprint Pro JS Agent between your site and Fingerprint CDN.
+- Proxying identification requests and responses between your site and Fingerprint Pro's APIs.
+
+This [improves](https://dev.fingerprint.com/docs/cloudfront-proxy-integration#the-benefits-of-using-the-cloudfront-integration) both accuracy and reliability of visitor identification and bot detection on your site.
+
+You can install the CloudFront proxy integration using a [CloudFormation template](https://github.com/fingerprintjs/fingerprint-pro-cloudfront-integration) or as a Terraform module included in this repository. For more details, see the [full documentation](https://dev.fingerprint.com/docs/cloudfront-proxy-integration-v2).
+
+## Requirements
+
+- AWS Account.
+- Access to an IAM role in AWS with privileges to manage IAM roles, CloudFront distributions, Secrets Manager, Lambda Functions, and S3 Read Only access.
+- Terraform project using the [AWS provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) with the IAM role described above.
+- [Terraform CLI](https://developer.hashicorp.com/terraform/tutorials/aws-get-started/install-cli).
+
+> [!IMPORTANT]  
+> The AWS CloudFront Proxy Integration is exclusively supported for customers on the Enterprise Plan. Other customers are encouraged to use [Custom subdomain setup](https://dev.fingerprint.com/docs/custom-subdomain-setup) or [Cloudflare Proxy Integration](https://dev.fingerprint.com/docs/cloudflare-integration).
+
+> [!WARNING]  
+> The underlying data contract in the identification logic can change to keep up with browser updates. Using the AWS CloudFront Proxy Integration might require occasional manual updates on your side. Ignoring these updates will lead to lower accuracy or service disruption.
+
+## How to install
+
+To set up CloudFront integration using Terraform, you need to:
+
+1. Add the Fingerprint Terraform module to your Terraform project.
+2. Use the module in the configuration of your CloudFront distribution.
+3. Deploy your Terraform project.
+4. Configure the Fingerprint Pro JS Agent on your site to communicate with your created Lambda@Edge function using the [scriptUrlPattern](https://dev.fingerprint.com/docs/js-agent#scripturlpattern) and [endpoint](https://dev.fingerprint.com/docs/js-agent#endpoint) parameters.
+
+See [CloudFront Proxy Integration guide](https://dev.fingerprint.com/docs/cloudfront-proxy-integration-v2) in our documentation for step-by-step instructions and follow the [Terraform installation method](https://dev.fingerprint.com/docs/aws-cloudfront-integration-via-terraform). If you have any questions, reach out to our [support team](https://fingerprint.com/support/).
+
+## Examples
+
+This repository also includes the following Terraform project examples:
+
+- [Adding the Fingerprint proxy integration to an existing CloudFront distribution](./examples//existing-ditribution/) (recommended)
+- [Creating a new CloudFront distribution just for the Fingerprint proxy integration](./examples/standalone-distribution/)
+
+## How to update
+
+The Terraform module does include any mechanism for automatic updates. To keep your integration up to date, please run `terraform apply` regularly.
+
+## License
+
+This project is licensed under the MIT license. See the [LICENSE](/LICENSE) file for more info.

examples/existing-ditribution/fingerprint.tf

@@ -0,0 +1,7 @@
+module "fingerprint_cloudfront_integration" {
+  source = "[email protected]:fingerprintjs/terraform-aws-fingerprint-cloudfront-proxy-integration.git"
+
+  fpjs_agent_download_path = var.fpjs_agent_download_path
+  fpjs_get_result_path     = var.fpjs_get_result_path
+  fpjs_shared_secret       = var.fpjs_shared_secret
+}

examples/existing-ditribution/main.tf

@@ -0,0 +1,98 @@
+resource "aws_cloudfront_distribution" "main_website_distribution" {
+  enabled             = true
+  is_ipv6_enabled     = true
+  comment             = "CloudFront distribution for ${var.website_origin_domain_name}"
+  default_root_object = "index.html"
+
+  origin {
+    domain_name = var.website_origin_domain_name
+    origin_id   = "your-website"
+
+    custom_origin_config {
+      http_port              = 80
+      https_port             = 443
+      origin_protocol_policy = "https-only"
+      origin_ssl_protocols   = ["TLSv1.2"]
+    }
+  }
+
+  default_cache_behavior {
+    allowed_methods  = ["GET", "HEAD"]
+    cached_methods   = ["GET", "HEAD"]
+    target_origin_id = "your-website"
+
+    forwarded_values {
+      query_string = false
+      cookies {
+        forward = "none"
+      }
+    }
+
+    viewer_protocol_policy = "redirect-to-https"
+    min_ttl                = 0
+    default_ttl            = 3600
+    max_ttl                = 86400
+  }
+
+  restrictions {
+    geo_restriction {
+      restriction_type = "none"
+    }
+  }
+
+  aliases = [var.website_domain]
+
+  viewer_certificate {
+    acm_certificate_arn = var.certificate_arn
+    ssl_support_method  = "sni-only"
+  }
+
+  #region Fingerprint CloudFront Integration start
+  origin {
+    domain_name = module.fingerprint_cloudfront_integration.fpjs_origin_name
+    origin_id   = module.fingerprint_cloudfront_integration.fpjs_origin_id
+    custom_origin_config {
+      origin_protocol_policy = "https-only"
+      http_port              = 80
+      https_port             = 443
+      origin_ssl_protocols   = ["TLSv1.2"]
+    }
+    custom_header {
+      name  = "FPJS_SECRET_NAME"
+      value = module.fingerprint_cloudfront_integration.fpjs_secret_manager_arn
+    }
+  }
+
+  ordered_cache_behavior {
+    path_pattern = "${var.fpjs_behavior_path}/*"
+
+    allowed_methods          = ["GET", "HEAD", "OPTIONS", "PUT", "POST", "PATCH", "DELETE"]
+    cached_methods           = ["GET", "HEAD"]
+    cache_policy_id          = module.fingerprint_cloudfront_integration.fpjs_cache_policy_id
+    origin_request_policy_id = module.fingerprint_cloudfront_integration.fpjs_origin_request_policy_id
+    target_origin_id         = module.fingerprint_cloudfront_integration.fpjs_origin_id
+    viewer_protocol_policy   = "https-only"
+    compress                 = true
+
+    lambda_function_association {
+      event_type   = "origin-request"
+      lambda_arn   = module.fingerprint_cloudfront_integration.fpjs_proxy_lambda_arn
+      include_body = true
+    }
+  }
+  #endregion
+}
+
+
+resource "aws_route53_record" "apex_domain" {
+  zone_id = var.domain_zone_id
+  name    = var.website_domain
+  type    = "A"
+
+  alias {
+    name                   = aws_cloudfront_distribution.main_website_distribution.domain_name
+    zone_id                = aws_cloudfront_distribution.main_website_distribution.hosted_zone_id
+    evaluate_target_health = false
+  }
+}
+

examples/existing-ditribution/providers.tf

@@ -0,0 +1,14 @@
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.57"
+    }
+  }
+
+  required_version = ">= 1.2.0"
+}
+
+provider "aws" {
+  region = "us-east-1"
+}

examples/existing-ditribution/terraform.tfvars.example

@@ -0,0 +1,8 @@
+fpjs_shared_secret         = "YOUR_PROXY_SECRET_CREATED_IN_FINGERPRINT_DASHBOARD"
+fpjs_agent_download_path   = "463N7"
+fpjs_get_result_path       = "r35U17"
+fpjs_behavior_path         = "fpj5"
+domain_zone_id             = "ZONE_ID_OF_YOUR_DOMAIN_IN_AWS"
+website_domain             = "yourwebsite.com"
+website_origin_domain_name = "your-website-origin.s3.amazonaws.com"
+certificate_arn            = "ARN_OF_THE_CERTIFICATE_OF_YOUR_DOMAIN_IN_AWS"

examples/existing-ditribution/variables.tf

@@ -0,0 +1,41 @@
+variable "fpjs_shared_secret" {
+  description = "The proxy secret for the Fingerprint proxy integration"
+  type        = string
+}
+
+variable "fpjs_behavior_path" {
+  description = "All Fingeprint requests will be proxied through this path segment"
+  type        = string
+}
+
+variable "fpjs_agent_download_path" {
+  description = "The Fingerprint agent download will be proxied through this path segment"
+  type        = string
+}
+
+variable "fpjs_get_result_path" {
+  description = "The Fingerprint identification request will be proxied through this path segment"
+  type        = string
+}
+
+variable "website_domain" {
+  description = "The domain for your existing CloudFront distribution, like `yourwebsite.com`"
+  type        = string
+}
+
+variable "website_origin_domain_name" {
+  description = "The main origin of your distribution pointing to your website, like `yourwebsite.s3.amazonaws.com`"
+  type        = string
+}
+
+variable "domain_zone_id" {
+  description = "Zone ID of the domain for your existing CloudFront distribution"
+  type        = string
+}
+
+variable "certificate_arn" {
+  description = "ARN of the domain certificate for your website"
+  type        = string
+}
+
+