AWS rtb-fabric documentation change
Summary
Added support for AWS CLI and CloudFormation configuration methods alongside API
Security assessment
This change only expands configuration options without introducing or modifying security controls. No security-specific content or warnings are added in this particular section.
Diff
diff --git a/rtb-fabric/latest/userguide/modules.md b/rtb-fabric/latest/userguide/modules.md index 3949b4f15..c56d042f8 100644 --- a//rtb-fabric/latest/userguide/modules.md +++ b//rtb-fabric/latest/userguide/modules.md @@ -43 +43 @@ All built-in modules are available at no additional charge. You can configure mu -Module configuration is only available through the RTB Fabric API. You cannot configure modules using the RTB Fabric console. Use the [UpdateLinkModuleFlow API operation](https://docs.aws.amazon.com/rtb-fabric/latest/api/API_UpdateLinkModuleFlow.html) to add, modify, or remove modules from your links. +You can configure modules using the RTB Fabric API, the AWS Command Line Interface (AWS CLI), or CloudFormation. The RTB Fabric console does not support module configuration. To add, modify, or remove modules from your links, use the [UpdateLinkModuleFlow](https://docs.aws.amazon.com/rtb-fabric/latest/api/API_UpdateLinkModuleFlow.html) API operation or its equivalent in the AWS CLI or CloudFormation. @@ -72 +72 @@ The following example shows how to add a QPS rate limiter module to a link using -The following example shows how to add an OpenRTB attribute module to a link using the AWS Command Line Interface (AWS CLI). +The OpenRTB Attribute Module filters bid requests based on attributes in the OpenRTB request payload. You define a set of filters to divide incoming bid requests into two groups: requests that match your filters and requests that do not. You then choose which group to apply an action to, such as returning a no-bid response or adding a custom HTTP header. This lets you intelligently shed traffic before it reaches your DSP, reducing compute and networking costs. @@ -74 +74,167 @@ The following example shows how to add an OpenRTB attribute module to a link usi -**Add an OpenRTB attribute module to a link** +###### Warning + +A misconfigured OpenRTB Attribute Module can unintentionally block desirable traffic. If you are unsure of the impact of a new filter configuration, we recommend starting with a high `holdbackPercentage` (for example, 90.0) and gradually decreasing it as you verify that only the intended traffic is being filtered. + +The module configuration is specified inside the `openRtbAttribute` object within `moduleParameters`. It contains the following fields: + + * `filterConfiguration` – An array of filters that define which bid requests to match. + + * `filterType` – Determines which group of requests the action applies to. + + * `action` – The action to perform on the selected group of requests. + + * `holdbackPercentage` – A percentage of requests that pass through regardless of filter results. + + + + +#### Filter criteria + +A _filter criterion_ is the smallest unit of a filter. Each criterion is a predicate on a single field in the OpenRTB bid request. A criterion contains two fields: + + * `key` – A JSON path expression that identifies a field in the bid request body. Use standard JSON path syntax starting with `$.` to navigate the OpenRTB request structure (for example, `$.device.geo.country`). + + * `values` – An array of strings representing the desired values. A criterion matches when the value retrieved from the bid request field is contained in this array. + + + + +The following example criterion matches bid requests where the COPPA (Children's Online Privacy Protection Act) flag is set to `1` (true): + + + { + "key": "$.regs.coppa", + "values": ["1"] + } + +The following example criterion matches bid requests originating from the United States or Canada: + + + { + "key": "$.device.geo.country", + "values": ["USA", "CAN"] + } + +###### Note + +The `values` field uses string matching. Numeric fields in the OpenRTB specification (such as `regs.coppa`) must be represented as strings in the `values` array (for example, `"1"` instead of `1`). + +#### Filters + +A _filter_ groups one or more filter criteria together using **AND** logic. All criteria within a filter must match for the filter to match a bid request. A filter contains a single field: + + * `criteria` – An array of filter criterion objects. + + + + +The following example filter matches bid requests that have the COPPA flag set to true **AND** originate from the United States or Canada. Both criteria must be satisfied: + + + { + "criteria": [ + { + "key": "$.regs.coppa", + "values": ["1"] + }, + { + "key": "$.device.geo.country", + "values": ["USA", "CAN"] + } + ] + } + +#### Filter configuration + +The `filterConfiguration` field is an array of filters combined using **OR** logic. A bid request matches the filter configuration if it matches _any one_ of the filters in the array. + +By combining AND logic within each filter and OR logic across filters, you can express complex filtering rules. The following example matches two types of requests: + + * Type A: Requests with COPPA flag set to true **AND** originating from the United States or Canada + + * **OR** + + * Type B: Requests from the domain `example.com` + + + + + + "filterConfiguration": [ + { + "criteria": [ + { + "key": "$.regs.coppa", + "values": ["1"] + }, + { + "key": "$.device.geo.country", + "values": ["USA", "CAN"] + } + ] + }, + { + "criteria": [ + { + "key": "$.site.domain", + "values": ["example.com"] + } + ] + } + ] + +#### Filter type + +The `filterType` field determines which group of bid requests the action applies to. After the filter configuration divides requests into two groups (matched and unmatched), the filter type selects which group receives the action. + + * `INCLUDE` – The action is performed on requests that _match_ the filter configuration. Use this when you want to target specific types of traffic (for example, block requests from certain regions). + + * `EXCLUDE` – The action is performed on requests that _do not match_ the filter configuration. Use this when you want to define the traffic you want to keep and apply the action to everything else. + + + + +#### Actions + +The `action` field specifies what to do with the selected group of bid requests. The following actions are available: + + * **No bid** (`noBid`) – Short-circuits the request and returns a no-bid response without forwarding it to the DSP. + +If you omit the `noBidReasonCode` field, the module returns an HTTP `204 No Content` response with no response body: + + "action": { + "noBid": {} + } + +If you specify a `noBidReasonCode`, the module returns an HTTP `200 OK` response with a JSON body containing the request ID (if present in the original bid request) and an `nbr` field set to the reason code you provided: + + "action": { + "noBid": { + "noBidReasonCode": 1 + } + } + + // Example response body: + // { "id": "request-123", "nbr": 1 } + + * **Header tag** (`headerTag`) – Adds a custom HTTP header to the request before forwarding it to the DSP. The request is not blocked; instead it is tagged with additional metadata. You specify a header `name` and `value`. + + "action": { + "headerTag": { + "name": "X-Custom-Filter", + "value": "coppa-flagged" + } + } + + + + +#### Holdback percentage + +The `holdbackPercentage` field specifies a percentage of requests (from 0.0 to 100.0) that pass through the module without any action being applied, regardless of whether they match the filter configuration. This is useful for A/B testing or for gradually rolling out filtering rules. For example, setting `holdbackPercentage` to `10.0` means 10% of requests bypass the module entirely. + +#### Examples + +**Example 1: Block COPPA-flagged traffic from specific countries** + +The following example returns an HTTP `204 No Content` for bid requests that have the COPPA flag set to true and originate from the United States or Canada: @@ -88 +254,146 @@ The following example shows how to add an OpenRTB attribute module to a link usi - "filterConfiguration": [], + "filterConfiguration": [ + { + "criteria": [ + { + "key": "$.regs.coppa", + "values": ["1"] + }, + { + "key": "$.device.geo.country", + "values": ["USA", "CAN"] + } + ] + } + ], + "action": { + "noBid": {} + }, + "holdbackPercentage": 0.0 + }