-
Notifications
You must be signed in to change notification settings - Fork 2
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #10 from fingerprintjs/docs/readme
docs(readme): mention how to install and how to use
- Loading branch information
Showing
2 changed files
with
196 additions
and
9 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,23 +1,210 @@ | ||
| <p align="center"> | ||
| <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" /> | ||
| <img src="https://fingerprintjs.github.io/home/resources/logo_dark.svg" alt="Fingerprint logo" width="312px" /> | ||
| </picture> | ||
| </a> | ||
| <p align="center"> | ||
| <a href="https://github.com/fingerprintjs/fingerprint-pro-akamai-integration-property-rules"> | ||
| <img src="https://img.shields.io/github/v/release/fingerprintjs/fingerprint-pro-akamai-integration-property-rules" alt="Current version"> | ||
| </a> | ||
| <a href="https://opensource.org/licenses/MIT"> | ||
| <img src="https://img.shields.io/:license-mit-blue.svg" alt="MIT license"> | ||
| </a> | ||
| <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> | ||
|
|
||
| > :warning: **Work in progress**: This is a beta version of the library | ||
| # Fingerprint Pro Akamai Integration Property Rules | ||
|
|
||
| [Fingerprint](https://fingerprint.com) is a device intelligence platform offering 99.5% accurate visitor identification. | ||
| The Fingerprint Akamai Integration Property Rules is the repository that contains property rules and variables for the Fingerprint Akamai proxy integration. | ||
|
|
||
| ## Requirements | ||
| - An Akamai property | ||
|
|
||
| > :warning: The Akamai integration is only available to Fingerprint customers on the Enterprise plan. Talk to our sales teams for more information. | ||
|
|
||
| ## How to install | ||
|
|
||
| > :warning: If you are not using Terraform, please contact our support. | ||
| If you are using Terraform to maintain your infrastructure, then go to [the latest release](https://github.com/fingerprintjs/fingerprint-pro-akamai-integration-property-rules/releases/latest), | ||
| you will find two files: | ||
| 1. Add `fingerprint-property-rules-for-terraform.json` file to the property's rules. You can find more info on this [here](https://techdocs.akamai.com/terraform/docs/set-up-property-provisioning#update-rules). | ||
| 2. Merge `fingerprint-property-variables-for-terraform.json` file with your property's variables file. You do this by modifying `rules.variables` path of your rules JSON. | ||
| 3. Make changes to your property's Terraform configuration. | ||
| 1. If you are using plain JSON file for rules and not using rules template, _please reach our support_. | ||
| 2. If you are using rules template, you need to specify 3 randomized values and the Fingerprint proxy secret. The 3 randomized paths are `fpjs_integration_path`, `fpjs_agent_path` and `fpjs_result_path`. You can use any valid URL paths for the 3 randomized values. | ||
| Go to the Fingerprint Dashboard [API Keys section](https://dashboard.fingerprint.com/api-keys) and press **+ Create Proxy Key** button to create the Fingerprint proxy secret. | ||
| ```hcl | ||
| data "akamai_property_rules_template" "rules" { | ||
| template_file = abspath("${path.root}/rules/main.json") # Assuming this is property's rules file | ||
| variables { | ||
| name = "fpjs_integration_path" | ||
| value = "YOUR_INTEGRATION_PATH_HERE" | ||
| type = "string" | ||
| } | ||
| variables { | ||
| name = "fpjs_agent_path" | ||
| value = "YOUR_AGENT_PATH_HERE" | ||
| type = "string" | ||
| } | ||
| variables { | ||
| name = "fpjs_result_path" | ||
| value = "YOUR_RESULT_PATH_HERE" | ||
| type = "string" | ||
| } | ||
| variables { | ||
| name = "fpjs_proxy_secret" | ||
| value = "YOUR_PROXY_SECRET_HERE" | ||
| type = "string" | ||
| } | ||
| } | ||
| ``` | ||
| The best practice for these fields is to use HashiCorp's [random provider](https://registry.terraform.io/providers/hashicorp/random/latest/docs), to use `variable` blocks and `terraform.tfvars` file. | ||
| The full example looks like below: | ||
| ```hcl | ||
| # property.tf file | ||
| resource "random_string" "fpjs_integration_path" { | ||
| length = 8 | ||
| special = false | ||
| lower = true | ||
| upper = false | ||
| numeric = true | ||
| } | ||
| resource "random_string" "fpjs_agent_path" { | ||
| length = 8 | ||
| special = false | ||
| lower = true | ||
| upper = false | ||
| numeric = true | ||
| } | ||
| resource "random_string" "fpjs_result_path" { | ||
| length = 8 | ||
| special = false | ||
| lower = true | ||
| upper = false | ||
| numeric = true | ||
| } | ||
| variable "fpjs_integration_path" { | ||
| type = string | ||
| validation { | ||
| condition = can(regex("(^$|^[a-zA-Z0-9-]+$)", var.fpjs_integration_path)) | ||
| error_message = "Variable value must be a valid URL path" | ||
| } | ||
| } | ||
| variable "fpjs_agent_path" { | ||
| type = string | ||
| validation { | ||
| condition = can(regex("(^$|^[a-zA-Z0-9-]+$)", var.fpjs_agent_path)) | ||
| error_message = "Variable value must be a valid URL path" | ||
| } | ||
| } | ||
| variable "fpjs_result_path" { | ||
| type = string | ||
| validation { | ||
| condition = can(regex("(^$|^[a-zA-Z0-9-]+$)", var.fpjs_result_path)) | ||
| error_message = "Variable value must be a valid URL path" | ||
| } | ||
| } | ||
| variable "fpjs_proxy_secret" { | ||
| type = string | ||
| validation { | ||
| condition = can(regex("^([a-zA-Z0-9-])+$", var.fpjs_proxy_secret)) | ||
| error_message = "Variable value must be obtained from Fingerprint dashboard" | ||
| } | ||
| } | ||
| locals { | ||
| fpjs_integration_path = var.fpjs_integration_path != "" ? var.fpjs_integration_path : random_string.fpjs_integration_path.result | ||
| fpjs_agent_path = var.fpjs_agent_path != "" ? var.fpjs_agent_path : random_string.fpjs_agent_path.result | ||
| fpjs_result_path = var.fpjs_result_path != "" ? var.fpjs_result_path : random_string.fpjs_result_path.result | ||
| } | ||
| data "akamai_property_rules_template" "rules" { | ||
| template_file = abspath("${path.root}/rules/main.json") # Assuming this is property's rules file | ||
| variables { | ||
| name = "fpjs_integration_path" | ||
| value = local.fpjs_integration_path | ||
| type = "string" | ||
| } | ||
| variables { | ||
| name = "fpjs_agent_path" | ||
| value = local.fpjs_agent_path | ||
| type = "string" | ||
| } | ||
| variables { | ||
| name = "fpjs_result_path" | ||
| value = local.fpjs_result_path | ||
| type = "string" | ||
| } | ||
| variables { | ||
| name = "fpjs_proxy_secret" | ||
| value = var.fpjs_proxy_secret | ||
| type = "string" | ||
| } | ||
| } | ||
| ``` | ||
| ```hcl | ||
| # terraform.tfvars file | ||
| fpjs_integration_path = "<value_from_tfstate>" | ||
| fpjs_agent_path = "<value_from_tfstate>" | ||
| fpjs_result_path = "<value_from_tfstate>" | ||
| fpjs_proxy_secret = "<value_from_fingerprint_dashboard>" | ||
| ``` | ||
| Note: You can leave the randomized values (`fpjs_integration_path`, `fpjs_agent_path` and `fpjs_result_path`) empty at first. They are known after `terraform apply` is run. You can then find them in the `terraform.tfstate` file and replace in your `terraform.tfvars` file. | ||
|
|
||
| 4. Run `terraform plan` to check your changes. If it asks you to provide values for randomized values, press enter to leave empty. They will be generated automatically. | ||
| 5. Run `terraform apply` to apply changes. If it asks you to provide values for randomized values, press enter to leave empty. They will be generated automatically. | ||
| 6. After `terraform apply` is completed and the property is activated, the installation is complete. You can then get randomized values from `terraform.tfstate` file and replace them inside `terraform.tfvars` file. | ||
|
|
||
| ## How to use | ||
|
|
||
| Configure Pro Agent with corresponding randomized paths: | ||
| ```js | ||
| const fpPromise = FingerprintJS.load({ | ||
| apiKey: "<your_fingerprint_public_key>", | ||
| endpoint: [ | ||
| "https://your-property.com/YOUR_INTEGRATION_PATH_HERE/YOUR_RESULT_PATH_HERE", // <- ADDED THIS | ||
| defaultEndpoint | ||
| ], | ||
| scriptUrlPattern: [ | ||
| "https://your-property.com/YOUR_INTEGRATION_PATH_HERE/YOUR_AGENT_PATH_HERE?apiKey=<apiKey>&version=<version>&loaderVersion=<loaderVersion>", // <- ADDED THIS | ||
| defaultScriptUrlPattern | ||
| ] | ||
| }) | ||
| ``` | ||
|
|
||
| ## How to build property rules | ||
|
|
||
| ### For Terraform | ||
| This section shows how to generate rules locally. This can be useful for those who don't use Terraform, don't use rules template or who want to make changes to the rules before applying them. | ||
| Please talk to Fingerprint support first if you need any help. | ||
|
|
||
| `yarn build --type terraform` | ||
| ### For Terraform | ||
|
|
||
| This command generates: | ||
| Run `yarn install`. Then run `yarn build --type terraform` to generate: | ||
| - `dist/terraform/json/fingerprint.json` | ||
| - `dist/terraform/json/variables.json` | ||
| - `dist/terraform/example.tf` | ||
|
|
||
| Which you can use in your current Terraform configuration. | ||
| files. Use them in your existing Terraform configuration. | ||
|
|
||
| ### For Akamai Public API (HTTP Patch Body) | ||
|
|
||
| ### For API (Patch Body) | ||
| Run `yarn install`. Then run `yarn build --type patchBody --integration-path YOUR_INTEGRATION_PATH_HERE --agent-path YOUR_AGENT_PATH_HERE --result-path YOUR_RESULT_PATH_HERE --proxy-secret YOUR_PROXY_SECRET_HERE`. This command generates `dist/patch-body/body.json`. This file includes all rules and property variables for the integration. Use Akamai's [public API](https://techdocs.akamai.com/property-mgr/reference/patch-property-version-rules) for applying it to your property. | ||
|
|
||
| `yarn build --type patchBody --integration-path abc --agent-path qwe --result-path klm --proxy-secret FPJSABC123 ` | ||
| ## License | ||
|
|
||
| This command generates `dist/patch-body` which contains `body.json`. | ||
| You can use this file to add Fingerprint Proxy Integration to your Akamai Property | ||
| This project is licensed under the MIT license. See the [LICENSE](https://github.com/fingerprintjs/fingerprint-pro-akamai-integration-property-rules/blob/main/LICENSE) file for more info. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters