|
| 1 | +--- |
| 2 | +layout: page_v2 |
| 3 | +sidebarType: 5 |
| 4 | +title: Prebid Server | Features | Privacy | US Custom Logic |
| 5 | +--- |
| 6 | + |
| 7 | +# Prebid Server US Custom Logic Privacy Module |
| 8 | +{:.no_toc} |
| 9 | + |
| 10 | +{: .alert.alert-warning :} |
| 11 | +This feature is currently only available in PBS-Java. |
| 12 | + |
| 13 | +- TOC |
| 14 | +{:toc} |
| 15 | + |
| 16 | +{: .alert.alert-danger :} |
| 17 | +Important: This resource should not be construed as legal advice and Prebid.org makes no guarantees about compliance with any law or regulation. Please note that because every company and its collection, use, and storage of personal data is different, you should seek independent legal advice relating to obligations under European and /or US regulations, including the GDPR, individual state laws, the ePrivacy Directive and CCPA. Only a lawyer can provide you with legal advice specifically tailored to your situation. Nothing in this guide is intended to provide you with, or should be used as a substitute for, legal advice tailored to your business. |
| 18 | + |
| 19 | +## Overview |
| 20 | + |
| 21 | +This module provides a way for publishers to define a custom interpretion for GPP strings in Sections 7-12. |
| 22 | +If the publisher is satisfied with Prebid's interpretation of GPP SIDs 7-12 as defined in |
| 23 | +[Prebid Multi-State Privacy Agreement Support](/features/mspa-usnat.html), it's recommended |
| 24 | +that they utilze the [US Gen Privacy Module](/prebid-server/features/pbs-usgen.html) instead of this one. |
| 25 | + |
| 26 | +This module lets publishers define GPP string interpretation with a powerful general syntax |
| 27 | +called [JsonLogic](https://jsonlogic.com/). At high traffic volumes with complex interpretion logic, |
| 28 | +the Prebid Server Host Company may want to monitor compute resource utilization consumed by use |
| 29 | +of this feature. Another option would be to build a [custom privacy module](/prebid-server/developers/add-a-privacy-module.html). |
| 30 | + |
| 31 | +The use cases for this module are the same as for the `US Gen Privacy Module`: |
| 32 | + |
| 33 | +- Is bidderA allowed to participate in this auction? |
| 34 | +- Is bidderB allowed to receive User First Party Data? |
| 35 | +- Is moduleM allowed to enrich the request with EIDs? |
| 36 | + |
| 37 | +The difference is that instead of the GPP interpretation logic being coded into the module, |
| 38 | +it allows publishers and their lawyers to come up with their own interpretations. As you'll see, this is powerful but complicated. |
| 39 | + |
| 40 | +## Using the US Custom Logic Privacy Module |
| 41 | + |
| 42 | +Some decisions are needed to activate the module within Prebid Server: |
| 43 | + |
| 44 | +1. The PBS host company needs to decide whether to enable this privacy module globally, per-account, or both. |
| 45 | +1. The host company also needs to decide whether to link this privacy module to Activity Controls globally. |
| 46 | +1. Publishers may ask the host company to override Activity Control defaults, including which activities use the module. |
| 47 | + |
| 48 | +### Enabling the US Custom Logic Module |
| 49 | + |
| 50 | +The US Custom Logic Privacy Module is included in PBS-Java 1.130, but is not activated until it's placed |
| 51 | +in the global or account-level config in a `privacy.modules` object. |
| 52 | + |
| 53 | +Here's an example: |
| 54 | + |
| 55 | +```json |
| 56 | +{ |
| 57 | + "privacy": { |
| 58 | + "modules": [{ |
| 59 | + "code": "iab.uscustomlogic", |
| 60 | + "config": { |
| 61 | + ... see below for examples ... |
| 62 | + } |
| 63 | + }], |
| 64 | + "allowactivities": { |
| 65 | + "ACTIVITY": { |
| 66 | + "default": true, |
| 67 | + "rules": [{ |
| 68 | + "privacyreg": ["*"] // causes the Activity Control to call all defined privacy modules |
| 69 | + }] |
| 70 | + } |
| 71 | +} |
| 72 | +``` |
| 73 | + |
| 74 | +### US Custom Logic Privacy Module Parameters |
| 75 | + |
| 76 | +Here are the parameters allowed in the module's `config` section. See below for examples. |
| 77 | + |
| 78 | +{: .table .table-bordered .table-striped } |
| 79 | +| Parameter | Type | Scope | Description | |
| 80 | +|------|------|-------------| |
| 81 | +| sids | array of integer | required | Process only the named section IDs. | |
| 82 | +| normalizeFlags | boolean | optional | Convert the state SIDs 8-12 into SID 7 fields as described in the [Prebid MSPA reference](/features/mspa-usnat.html). Defaults to `true`. | |
| 83 | +| activityConfig | array of objects | required | Defines what processing to do. | |
| 84 | +| activityConfig[].activities | array of strings | required | Defines which activity or activities are in scope for this array entry. | |
| 85 | +| activityConfig[].restrictIfTrue | object | required | [JsonLogic](https://jsonlogic.com) rules object. | |
| 86 | + |
| 87 | +### JsonLogic Data Fields |
| 88 | + |
| 89 | +{: .alert.alert-info :} |
| 90 | +Tip: Scroll down to the example to see what a JsonLogic rule (the `restrictIfTrue` field) looks like. The config only needs to contain the JsonLogic rule -- the module will create the JsonLogic data |
| 91 | +from the GPP string. |
| 92 | + |
| 93 | +The way [JsonLogic](https://jsonlogic.com) works is that you supply two JSON objects: |
| 94 | + |
| 95 | +1. A set of rules. This defines boolean logic with many operators. For this module, the configuration defines the rules in the `restrictIfTrue` field. |
| 96 | +1. A set of data. The module parses the GPP string and creates a set of attribute-value pairs for each flag defined in the GPP section. |
| 97 | + |
| 98 | +The specific fields produced by the module that can be referred to in a rule are based on the IAB's definition of each SID. The only difference is that array fields simply have a number appended since JsonLogic doesn't support arrays. |
| 99 | + |
| 100 | +These are the fields that can be referenced in the JsonLogic rule: |
| 101 | + |
| 102 | +- MspaServiceProviderMode |
| 103 | +- MspaCoveredTransaction |
| 104 | +- MspaOptOutOptionMode |
| 105 | +- Gpc |
| 106 | +- SaleOptOutNotice |
| 107 | +- SaleOptOut |
| 108 | +- SharingNotice |
| 109 | +- SharingOptOutNotice |
| 110 | +- SharingOptOut |
| 111 | +- TargetedAdvertisingOptOutNotice |
| 112 | +- TargetedAdvertisingOptOut |
| 113 | +- KnownChildSensitiveDataConsents1 |
| 114 | +- KnownChildSensitiveDataConsents2 |
| 115 | +- PersonalDataConsents |
| 116 | +- SensitiveDataProcessingOptOutNotice |
| 117 | +- SensitiveDataLimitUseNotice |
| 118 | +- SensitiveDataProcessing1 |
| 119 | +- SensitiveDataProcessing2 |
| 120 | +- SensitiveDataProcessing3 |
| 121 | +- SensitiveDataProcessing4 |
| 122 | +- SensitiveDataProcessing5 |
| 123 | +- SensitiveDataProcessing6 |
| 124 | +- SensitiveDataProcessing7 |
| 125 | +- SensitiveDataProcessing8 |
| 126 | +- SensitiveDataProcessing9 |
| 127 | + |
| 128 | +See the IAB technical specifications for the definition and values allowed for each field. e.g. [GPP Extension: IAB Privacy’s US National Privacy Technical Specification](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/US-National/IAB%20Privacy%E2%80%99s%20National%20Privacy%20Technical%20Specification.md) |
| 129 | + |
| 130 | +### Linking the module to Activities |
| 131 | + |
| 132 | +The US Custom Logic Privacy Module will not operate within the PBS workflow unless it's called by the Activity Control system. e.g. |
| 133 | + |
| 134 | +```javascript |
| 135 | +{ |
| 136 | + "privacy": { |
| 137 | + "allowactivities": { |
| 138 | + "ACTIVITY": { |
| 139 | + "default": true, |
| 140 | + "rules": [{ |
| 141 | + "privacyreg": ["*"] // this causes the Activity Control to call this module |
| 142 | + },{ |
| 143 | + ... more rules ... |
| 144 | + }] |
| 145 | + } |
| 146 | + } |
| 147 | + } |
| 148 | +} |
| 149 | +``` |
| 150 | + |
| 151 | +### Example 1 - Handle GPC and 'sensitive data' differently |
| 152 | + |
| 153 | +Again, publishers will only use this module if their lawyers disagree with Prebid's default |
| 154 | +interpretation of the US National or US State GPP strings. |
| 155 | + |
| 156 | +As one example, Prebid interprets the Global Privacy Control (GPC) flag as a strong privacy signal that disables many GPP |
| 157 | +privacy-related activities. Say a publisher's lawyers want to allow the `transmitUfpd` activity to operate in the US even when the GPC flag is set to true. In addition, they've declared that |
| 158 | +they don't operate in any "sensitive data" category, so wish to remove those elements from |
| 159 | +interpretation. |
| 160 | + |
| 161 | +Here's an example config: |
| 162 | + |
| 163 | +```json |
| 164 | +{ |
| 165 | + "privacy": |
| 166 | + { |
| 167 | + "modules": [{ |
| 168 | + "code": "iab.uscustomlogic", |
| 169 | + "config": { |
| 170 | + "sids": [7,8,9,10,11,12], |
| 171 | + "normalizeFlags": true, |
| 172 | + "activityConfig": [{ |
| 173 | + "activities": ["transmitUfpd"], |
| 174 | + "restrictIfTrue": { |
| 175 | + "or": [ |
| 176 | + { "==": [{"var": "MspaServiceProviderMode"},1] }, |
| 177 | + { "and": [ |
| 178 | + { "==": [{"var": "MspaServiceProviderMode"},2] }, |
| 179 | + { "or": [ |
| 180 | + { "==": [{"var": "SaleOptOut"},1] }, |
| 181 | + { "==": [{"var": "SaleOptOutNotice"},2] }, |
| 182 | + { "==": [{"var": "SharingNotice"},2] }, |
| 183 | + { "==": [{"var": "SharingOptOut"},1] }, |
| 184 | + { "==": [{"var": "TargetedAdvertisingOptOutNotice"},2] }, |
| 185 | + { "==": [{"var": "TargetedAdvertisingOptOut"},1] }, |
| 186 | + { "!=": [{"var": "KnownChildSensitiveDataConsents1"},0] }, |
| 187 | + { "!=": [{"var": "KnownChildSensitiveDataConsents2"},0] }, |
| 188 | + { "==": [{"var": "PersonalDataConsents"},2] } |
| 189 | + ]} |
| 190 | + ]} |
| 191 | + ]} |
| 192 | + }] |
| 193 | + } |
| 194 | + },{ |
| 195 | + "code": "iab.usgen", |
| 196 | + "config": { skipSids: [] } |
| 197 | + }], |
| 198 | + "allowactivities": { |
| 199 | + "transmitUfpd": { |
| 200 | + "default": false, |
| 201 | + "rules": [{ |
| 202 | + "privacyreg": ["iab.uscustomlogic"] |
| 203 | + }] |
| 204 | + }, |
| 205 | + "transmitPreciseGeo": { |
| 206 | + "default": false, |
| 207 | + "rules": [{ |
| 208 | + "privacyreg": ["iab.usgen"] |
| 209 | + }] |
| 210 | + } |
| 211 | + } |
| 212 | + } |
| 213 | +} |
| 214 | +``` |
| 215 | + |
| 216 | +Notes: |
| 217 | + |
| 218 | +- In this example, only one activity uses the custom logic. Other activities utilize the conventions coded into the iab.usgen module. |
| 219 | +- It would be possible to link each activity to different parsing logic |
| 220 | + |
| 221 | +### Example 2 - Process Native GPP SID 11 Flags |
| 222 | + |
| 223 | +In this example, a publisher's lawyers have determined that Prebid's normalization of Utah (SID 11) to the US National (SID 7) equivalents should not be used. This is somewhat contrived, but illustrates that you can operate |
| 224 | +on non-normalized GPP flags. |
| 225 | + |
| 226 | +```javascript |
| 227 | +{ |
| 228 | + "privacy": |
| 229 | + { |
| 230 | + "modules": [{ |
| 231 | + "code": "iab.uscustomlogic", |
| 232 | + "config": { |
| 233 | + "sids": [11], |
| 234 | + "normalizeFlags": false, // note: normalization to SID 7 not performed |
| 235 | + "activityConfig": [{ |
| 236 | + "activities": ["transmitUfpd"], |
| 237 | + "restrictIfTrue": { |
| 238 | + ... JsonLogic Rule refers to Utah-definitions ... |
| 239 | + ... e.g. SensitiveDataProcessing3 and SensitiveDataProcessing4 are reversed ... |
| 240 | + },{ |
| 241 | + ... other activities ... |
| 242 | + }] |
| 243 | + } |
| 244 | + },{ |
| 245 | + "code": "iab.usgen", |
| 246 | + "config": { |
| 247 | + "skipSids": [11] |
| 248 | + } |
| 249 | + }], |
| 250 | + "allowactivities": { |
| 251 | + "transmitUfpd": { |
| 252 | + "default": false, |
| 253 | + "rules": [{ |
| 254 | + "privacyreg": ["*"] |
| 255 | + }] |
| 256 | + }, |
| 257 | + ... other activities ... |
| 258 | + } |
| 259 | + } |
| 260 | +} |
| 261 | +``` |
| 262 | + |
| 263 | +### Module Processing |
| 264 | + |
| 265 | +Here's how the module works when called by an Activity Control: |
| 266 | + |
| 267 | +1. Gather GPP data |
| 268 | + 1. GPP string comes from `regs.gpp` |
| 269 | + 1. The GPP SIDs come from `regs.gpp_sid`. This is an array of integers. |
| 270 | +1. Check the GPP SIDs to see if this request is in-scope |
| 271 | + 1. If there are no GPP SIDs, return `abstain`. |
| 272 | +1. For each GPP SID defined in the request |
| 273 | + 1. If the SID is < 7 or > 12, go on to the next SID |
| 274 | + 1. Else if the SID is not on the sids list, go on to the next SID |
| 275 | + 1. Else pull that section of out the GPP string and process it |
| 276 | + 1. If the normalizeFlags option is true and the SID is 8-12, normalize the flags to the SID 7 form as described in the Prebid [MSPA/USNat reference](/features/mspa-usnat.html). |
| 277 | + 1. Find the current activity. If found, run the JsonLogic in the `restrictIfTrue` section as the rule, and pass in the GPP SID flags as the data. If the result is true, then "allow=false". |
| 278 | + 1. On first "allow: false" immediately return `allow: false` to the Activity Control system. |
| 279 | + 1. Continue until all SIDs are processed or skipped. |
| 280 | +1. If any SID returns "allow: true", return `allow: true` to the Activity Control system |
| 281 | +1. Otherwise return `abstain` |
| 282 | + |
| 283 | +### Limits |
| 284 | + |
| 285 | +Because the module config is not an array, it is not be possible to create |
| 286 | +rules that apply to each US state's non-normalized GPP flags for the same activity. |
| 287 | + |
| 288 | +Supporting this scenario would require a PBS Host Company to build a custom privacy module. |
| 289 | + |
| 290 | +### Troubleshooting |
| 291 | + |
| 292 | +Additional information about the outcoming of privacy module processing can be obtained by setting `ext.prebid.trace: "basic"`. |
| 293 | + |
| 294 | +It may be useful to use the [JsonLogic tool](https://jsonlogic.com/play.html) to confirm the desired logic: |
| 295 | + |
| 296 | +1. Enter a rule just as you would for the `restrictIfTrue` object. |
| 297 | +1. Enter a simple JSON object containing the desired values of the GPP flags. |
| 298 | + |
| 299 | +Here's a screenshot showing the usage of that tool: |
| 300 | + |
| 301 | +{:class="pb-xlg-img"} |
| 302 | + |
| 303 | +## Related Topics |
| 304 | + |
| 305 | +- [Prebid Multi-State Privacy Agreement Support](/features/mspa-usnat.html) |
| 306 | +- [US General Privacy Module](/prebid-server/features/pbs-usgen.html) |
| 307 | +- [Activity Control system](/prebid-server/features/pbs-activitycontrols.html) |
| 308 | +- [IAB US National Privacy Specification](https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/US-National/IAB%20Privacy%E2%80%99s%20National%20Privacy%20Technical%20Specification.md) |
0 commit comments