diff --git a/README.md b/README.md index 6e292e1..997dbf6 100644 --- a/README.md +++ b/README.md @@ -58,19 +58,50 @@ Each origin is required to have a JSON configuration object available in the Red `jasima:config:`. The following keys are meaningful in this object: -| Key | Description | Default | Example | -|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|-----------------------------| -| `geo_redirect_disable` | Disables redirecting to the canonical host when a mirror likely isn't needed based on the viewer's geography. | Requests are redirected based on a hardcoded list of countries unlikely to have implemented censorship. | `true` | -| `headers` | Append additional headers to the request sent to the origin. | No additional headers are added. | `{"X-Example": "Hello"}` | -| `host_connect` | Override the hostname that is used to connect to the origin. This can be useful in the case that the origin is begind a CDN that you want to avoid having to traverse, either due to DDoS protection tools being falsely triggered or simply to save costs. | The canonical host is used. | `"real-origin.example.com"` | -| `host_header` | Override the hostname that is used as the `Host` header when connecting to the origin. | The canonical host is used. | `"news.example.org"` | -| `host_ssl` | Override the hostname that is used for TLS SNI and for verification of the upstream's TLS certificate. | The canonical host is used. | `"news.example.org"` | -| `matomo_site_id` | The site ID to use for Matomo tracking. | No tracking code is added to HTML pages. | `20` | -| `rewrite_case_insensitive` | Rewrite references to other domain names using a case-insensitive match. This requires the use of the PCRE engine which is approximately 10% of the speed of the Lua pattern matching engine, so only enable if required. | Domains are matched based on the case in the pool mapping. | `true` | -| `rewrite_disable` | Disable content rewriting for this host. This disables both URL rewriting, and the addition of Matomo tracking code, but not the replacement of absolute links to the canonical hostname with relative links. | Rewriting is enabled. | `true` | +| Key | Description | Default | Example | +|----------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------|-----------------------------------------------| +| `first_party_adobe` | See section below. | Feature disabled. | `{"subdomain": "ssc", "account": "example"}` | +| `first_party_tealium` | See section below. | Feature disabled. | `{"subdomain": "tags", "account": "example"}` | +| `geo_redirect_disable` | Disables redirecting to the canonical host when a mirror likely isn't needed based on the viewer's geography. | Requests are redirected based on a hardcoded list of countries unlikely to have implemented censorship. | `true` | +| `headers` | Append additional headers to the request sent to the origin. | No additional headers are added. | `{"X-Example": "Hello"}` | +| `host_connect` | Override the hostname that is used to connect to the origin. This can be useful in the case that the origin is begind a CDN that you want to avoid having to traverse, either due to DDoS protection tools being falsely triggered or simply to save costs. | The canonical host is used. | `"real-origin.example.com"` | +| `host_header` | Override the hostname that is used as the `Host` header when connecting to the origin. | The canonical host is used. | `"news.example.org"` | +| `host_ssl` | Override the hostname that is used for TLS SNI and for verification of the upstream's TLS certificate. | The canonical host is used. | `"news.example.org"` | +| `matomo_site_id` | The site ID to use for Matomo tracking. | No tracking code is added to HTML pages. | `20` | +| `rewrite_case_insensitive` | Rewrite references to other domain names using a case-insensitive match. This requires the use of the PCRE engine which is approximately 10% of the speed of the Lua pattern matching engine, so only enable if required. | Domains are matched based on the case in the pool mapping. | `true` | +| `rewrite_disable` | Disable content rewriting for this host. This disables both URL rewriting, and the addition of Matomo tracking code, but not the replacement of absolute links to the canonical hostname with relative links. | Rewriting is enabled. | `true` | Note: the default case applies when the key is omitted. +### 🍪 First-Party Tealium & Adobe Analytics + +**Watch Out!** This feature was implemented specifically for the US Agency for Global Media and may not work correctly +for others. If it works for you, then great. If it doesn't, we could potentially accept a pull request that either +adapts the existing feature, or just adds a new one for you. If you're so inclined then we'd be really happy to accept +a feature that allowed for custom Lua code to be added on a per-deployment basis. + +The configuration for both services are the same. The assumption is that the first-party subdomain chosen is always a +subdomain of the registered domain name (i.e. an extension on the Mozilla Public Suffix List + one name). For example: + +| Site | Registered Domain | First-Party App Subdomain | +|-----------------|-------------------|---------------------------| +| www.example.com | example.com | tags.example.com | +| ir.example.com | example.com | tags.example.com | +| example.com | example.com | tags.example.com | + +In this example, the `subdomain` property to configure for this app would be `"tags"`. + +The account name is the account name registered with the application. You can usually find this from the URL provided +to you for inclusion in your HTML. + +**Tealium:** The Universal Tag code contains a URL that looks like: +`//tags.tiqcdn.com/utag/ACCOUNT/PROFILE/ENVIRONMENT/utag.js`. +The `ACCOUNT` here should be used for the `account` property in the configuration. + +**Adobe Analytics:** Look for a URL like: +`https://ACCOUNT.sc.omtrdc.net/b/ss/`. +Again, `ACCOUNT` is what should be used for the `account` property in the configuration. + ## 🖋️ Copyright Copyright © 2025 SR2 Communications Limited.