One String for a Dozen State Laws
The US privacy patchwork keeps growing: California, Virginia, Colorado, Connecticut, Utah, Texas, Oregon, and more, each with its own opt-out rules. The IAB's answer for ad tech is the US National (usnat) technical specification, which encodes a superset of these obligations into a single section inside the GPP string. Rather than juggle a separate signal per state, a publisher can express one national posture and let downstream vendors read the fields relevant to the user's state.
usnat implements the Multi-State Privacy Agreement (MSPA), IAB's contractual framework for how signatories process data under these laws. This guide walks the field groups so you know what you're actually encoding. For the browser-side opt-out signal that feeds several of these fields, see the Global Privacy Control guide.
Where usnat Sits in the Container
Inside the GPP container, usnat is Section 7. A CMP that supports it advertises "7:usnat" in its supportedAPIs array, and when the section applies to a visitor, the CMP sets applicableSections to [7]. The per-state sections (California is 8, Virginia 9, Colorado 10, and so on up through the newer states) carry the same field patterns scoped to one state. Many deployments encode usnat as the primary national signal and let vendors map it onto the visitor's jurisdiction.
The Opt-Out Fields Are the Point
Three fields carry the user's actual choices, and all three use the same 2-bit encoding:
- SaleOptOut: has the user opted out of the sale of their personal information?
- SharingOptOut: have they opted out of sharing for cross-context behavioral advertising?
- TargetedAdvertisingOptOut: have they opted out of targeted advertising?
The value encoding is where implementers slip. Each field is 0 for Not Applicable, 1 for Opted Out (the user said no), and 2 for Did Not Opt Out (the user was asked and did not opt out). The counterintuitive part is that 2, the higher number, is the permissive state. A brand-new visitor who hasn't interacted yet should read 0, not 2: you can't claim they declined to opt out before you asked. CookieBeam's mapper follows exactly this rule, emitting 0 when there's no consent interaction yet, 1 when the relevant category is rejected or GPC is present, and 2 only when the user affirmatively left it on.
Notice Fields Are Publisher Assertions
A second group of fields (SharingNotice, SaleOptOutNotice, SharingOptOutNotice, TargetedAdvertisingOptOutNotice, SensitiveDataProcessingOptOutNotice, and others) isn't about the individual user at all. These are the publisher asserting that it provided the required notices. They're configured by the publisher, not derived from a click, and they default to 0 (Not Applicable) until you set them to reflect the notices your site actually shows.
Don't set these to 1 reflexively to look compliant. A notice field claims you did something. If you assert you provided a sensitive-data opt-out notice that isn't actually on your page, you've encoded a false statement into a signal ad tech partners rely on.
Sensitive Data and Known Child Consents
usnat carries a SensitiveDataProcessing array, sixteen entries in the national section, each a 2-bit value covering a category of sensitive data (health, precise geolocation, racial or ethnic origin, and so on). Alongside it, KnownChildSensitiveDataConsents handles data about minors. These consent-style fields flip the polarity of the opt-out fields: for them, 1 means No Consent and 2 means Consent, with 0 still Not Applicable. PersonalDataConsents follows the same consent semantics.
Most publishers leave the sensitive-data array at 0 unless they actually process those categories, and configure the child-consent fields according to how their site handles minors. The point is that these are deliberate, publisher-configured values, not something a generic accept button should populate.
The MSPA Fields
Three fields declare the publisher's MSPA posture: MspaCoveredTransaction states whether the transaction is covered by the agreement, MspaOptOutOptionMode and MspaServiceProviderMode declare which mode the publisher operates under. Like the notice fields, these are assertions the publisher configures, and they matter to signatory vendors deciding how they may process the data. They also default to Not Applicable until set.
GPC Rides in Its Own Segment
The Global Privacy Control signal gets first-class treatment in usnat. There's a Gpc boolean and a GPC segment (GpcSegmentType, GpcSegmentIncluded) so the signal travels distinctly within the encoded string. This matters because GPC is legally a valid opt-out under several state laws, so a browser sending GPC should drive the sale, sharing, and targeted-advertising opt-outs to 1 even before the user touches your banner. CookieBeam's mapper honors this: when GPC is detected, it forces those opt-outs to Opted Out regardless of banner state.
usnat v1 and v2
The specification has moved forward. Google announced support for GPP National v2 starting in September 2025, while continuing to support v1. If you're building now, encode against the version your key downstream partners consume and confirm which version they expect, because a v2 string sent to a v1-only reader, or the reverse, can be misread. Track the field-set differences rather than assuming they're interchangeable.
CookieBeam encodes usnat through the official @iabgpp/cmpapi library, which owns the bit-level field ordering, so the runtime's job is to map consent categories and GPC state onto the right field values and let the library serialize. For the transport that carries this section, see the GPP __gpp() API guide.