iabconsent

package module
v0.5.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 31, 2023 License: MIT Imports: 7 Imported by: 2

README

iabconsent

Build Status

Go Report Card

A Golang implementation of the:

  • IAB Consent String 1.1 Spec
  • IAB Transparency and Consent String v2.0-v2.2
  • IAB Tech Lab Global Privacy Platform (GPP) Spec v1.0 Sections:
    • US National Multi-State Privacy Agreement
    • US California Multi-State Privacy Agreement
    • US Virginia Multi-State Privacy Agreement
    • US Colorado Multi-State Privacy Agreement
    • US Utah Multi-State Privacy Agreement
    • US Connecticut Multi-State Privacy Agreement

To install:

go get -v github.com/LiveRamp/iabconsent

This package defines two structs (ParsedConsent and V2ParsedConsent) which contain all of the fields of the IAB TCF v1.1 Consent String and the IAB Transparency and Consent String v2.0 respectively.

Each spec has their own parsing function (ParseV1 and ParseV2). If the caller is unsure of which version a consent string is, they can use TCFVersionFromTCString to receive a TCFVersion enum type to determine which parsing function is appropriate.

Example use:

package main

import "github.com/LiveRamp/iabconsent"

func main() {
    var consent = "COvzTO5OvzTO5BRAAAENAPCoALIAADgAAAAAAewAwABAAlAB6ABBFAAA"

    var c, err = iabconsent.TCFVersionFromTCString(consent)
    if err != nil {
        panic(err)
    }
    
    switch c {
    case iabconsent.V1:
        var v1, err = iabconsent.ParseV1(consent)
        // Use v1 consent.
    case iabconsent.V2:
        var v2, err = iabconsent.ParseV2(consent)
        // Use v2 consent.
    default:
        panic("unknown version")
    }
}

The function Parse(s string) is deprecated, and should no longer be used.

Global Privacy Platform v1.0

This package defines two structs (GPPHeader and GppParsedConsent) which contain the fields of the GPP Header and GPP Sections respectively. GppParsedConsent itself is broad, as a given GPP String may contain different sections that have their own unique privacy specifications.

All supported sections of the Multi-State Privacy Agreement via GPP have their own struct MspaParsedConsent.

There are two ways of working with the GPP string.

  1. Getting the Parsing Functions
    • MapGppSectionToParser takes the full string, parses and processes the header to get the remaining sections, and maps sections to a parsing function (if supported). This allows the user to determine how/when they want to parse the sections.
  2. Parse the Entire String
    • ParseGppConsent takes the full string, parses and process the header and all supported sections consecutively, returning the ParsedConsents.

Example use:

package main

import "github.com/LiveRamp/iabconsent"

func main() {
	var consent = "DBABrGA~BVVqAAEABCA~BVoYYZoI~BVoYYYI~BVoYYQg~BVaGGGCA~BVoYYYQg"

	// Parse Entire String via function.
	var gppConsents, err = iabconsent.ParseGppConsent(consent)
	if err != nil {
		panic(err)
	}
	var usNational = gppConsents[7]
	var mspa, ok = usNational.(*iabconsent.MspaParsedConsent)
	if !ok {
		// Not MSPA ParsedConsent
	}
	if mspa.Version == 1 {
		// Can check specific values/fields to determine your own requirements to process.
	}

	// Get Parsing Functions, and parse on your own.
	var gppConsentFunctions, errMap = iabconsent.MapGppSectionToParser(consent)
	if errMap != nil {
		panic(err)
	}
	var usNationalParsed iabconsent.GppParsedConsent
	var errParse error
	for _, gppSection := range gppConsentFunctions {
		if gppSection.GetSectionId() == 7 {
			usNationalParsed, errParse = gppSection.ParseConsent()
			if errParse != nil {
				panic(err)
			}
		}
	}

	var parsed, pOk = usNationalParsed.(*iabconsent.MspaParsedConsent)
	if !pOk {
		// Not MSPA ParsedConsent
	}
	if parsed.Version == 1 {
		// Can check specific values/fields to determine your own requirements to process.
	}
}

Documentation

Overview

Package iabconsent provides structs and methods for parsing vendor consent strings as defined by the IAB. Current two versions of consent strings are supported.

The IAB Consent String 1.1 Spec which can be found here: https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/47b45ab362515310183bb3572a367b8391ef4613/Consent%20string%20and%20vendor%20list%20formats%20v1.1%20Final.md#vendor-consent-string-format-

The IAB Transparency and Consent String 2 Spec which can be found here: https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/47b45ab362515310183bb3572a367b8391ef4613/TCFv2/IAB%20Tech%20Lab%20-%20Consent%20string%20and%20vendor%20list%20formats%20v2.md#about-the-transparency--consent-string-tc-string

Copyright (c) 2020 LiveRamp. All rights reserved.

Written by Andy Day, Software Engineer @ LiveRamp for use in the LiveRamp Pixel Server.

Index

Constants

View Source 
const (
	UsNationalSID = iota + 7
	UsCaliforniaSID
	UsVirginiaSID
	UsColoradoSID
	UsUtahSID
	UsConnecticutSID
)

Variables

View Source 
var PrecompiledFibonacci = map[int]int{0: 0, 1: 1, 2: 1, 3: 2, 4: 3, 5: 5, 6: 8, 7: 13, 8: 21, 9: 34, 10: 55, 11: 89, 12: 144, 13: 233}

Functions

func FibonacciIndexValue added in v0.5.0 

func FibonacciIndexValue(index int) (int, error)

FibonacciIndexValue is a helper function to get the Fibonacci value of an index for Fibonacci encoding. These are currently only used for the various consent types, which there are not many, so we should only expect to use the smaller indexes. Therefore, create a map, but still allow for new indexes to be calculated.

func ParseGpcSubsection added in v0.5.0 

func ParseGpcSubsection(r *ConsentReader) (bool, error)

ParseGpcSubsection reads the next bit as a bool, and returns the result of value. Info about GPC subsection here: https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/606b99efc16b649c5c1f8f1d2eb0d0d3258c4a2d/Sections/US-National/IAB%20Privacy%E2%80%99s%20National%20Privacy%20Technical%20Specification.md#gpc-sub-section

func ParseGppConsent added in v0.5.0 

func ParseGppConsent(s string) (map[int]GppParsedConsent, error)

ParseGppConsent takes a base64 Raw URL Encoded string which represents a GPP v1 string and returns a map of Section ID to ParsedConsents with consent parsed via a consecutive parsing.

Types

type ConsentReader added in v0.2.0 

type ConsentReader struct {
	*bits.Reader
}

ConsentReader provides additional Consent String-specific bit-reading functionality on top of bits.Reader.

func NewConsentReader added in v0.2.0 

func NewConsentReader(src []byte) *ConsentReader

NewConsentReader returns a new ConsentReader backed by src.

func (*ConsentReader) ReadBitField added in v0.2.0 

func (r *ConsentReader) ReadBitField(n uint) (map[int]bool, error)

ReadBitField reads the next n bits and converts them to a map[int]bool.

func (*ConsentReader) ReadFibonacciInt added in v0.5.0 

func (r *ConsentReader) ReadFibonacciInt() (int, error)

ReadFibonacciInt reads all the bits until two consecutive `1`s, and converts the bits to an int using Fibonacci Encoding. More info: https://en.wikipedia.org/wiki/Fibonacci_coding

func (*ConsentReader) ReadFibonacciRange added in v0.5.0 

func (r *ConsentReader) ReadFibonacciRange() ([]int, error)

ReadFibonacciRange reads a range entries of Fibonacci encoded integers. Returns an array of numbers. The format of the range field always consists of: - int(12) - representing the amount of items to follow - (per item) Boolean - representing whether the item is a single ID (0/false) or a group of IDs (1/true) - (per item) int(Fibonacci) - representing a) the offset to a single ID or b) the offset to the start ID in case of a group (the offset is from the last seen number, or 0 for the first entry) - (per item + only if group) int(Fibonacci) - length of the group

func (*ConsentReader) ReadInt added in v0.2.0 

func (r *ConsentReader) ReadInt(n uint) (int, error)

ReadInt reads the next n bits and converts them to an int.

func (*ConsentReader) ReadMspaBitfieldConsent added in v0.5.0 

func (r *ConsentReader) ReadMspaBitfieldConsent(l uint) (map[int]MspaConsent, error)

ReadMspaBitfieldConsent reads n-bitfield values, and converts the values into MSPA Consent values.

func (*ConsentReader) ReadMspaBitfieldOptOut added in v0.5.2 

func (r *ConsentReader) ReadMspaBitfieldOptOut(l uint) (map[int]MspaOptout, error)

ReadMspaBitfieldOptOut reads n-bitfield values, and converts the values into MSPA OptOut values.

func (*ConsentReader) ReadMspaConsent added in v0.5.0 

func (r *ConsentReader) ReadMspaConsent() (MspaConsent, error)

ReadMspaConsent reads integers into standard Consent values of 0: Not Applicable, 1: Not Consent, 2: Consent

func (*ConsentReader) ReadMspaNaYesNo added in v0.5.0 

func (r *ConsentReader) ReadMspaNaYesNo() (MspaNaYesNo, error)

ReadMspaNaYesNo is a helper function to handle the responses to standard MSPA values that are in the same format of 0: Not Applicable, 1: Yes, 2: No.

func (*ConsentReader) ReadMspaNotice added in v0.5.0 

func (r *ConsentReader) ReadMspaNotice() (MspaNotice, error)

ReadMspaNotice reads integers into standard MSPA Notice values of 0: Not applicable, 1: Yes, notice was provided, 2: No, notice was not provided.

func (*ConsentReader) ReadMspaOptOut added in v0.5.0 

func (r *ConsentReader) ReadMspaOptOut() (MspaOptout, error)

ReadMspaOptOut reads integers into standard MSPA OptOut values of 0: Not Applicable, 1: Opted out, 2: Did not opt out

func (*ConsentReader) ReadNBitField added in v0.5.0 

func (r *ConsentReader) ReadNBitField(n, l uint) (map[int]int, error)

ReadNBitField reads n bits, l number of times and converts them to a map[int]int. This allows a variable number of bits to be read for more possible number values.

func (*ConsentReader) ReadPubRestrictionEntries added in v0.3.0 

func (r *ConsentReader) ReadPubRestrictionEntries(n uint) ([]*PubRestrictionEntry, error)

ReadPubRestrictionEntries reads n publisher restriction entries.

func (*ConsentReader) ReadPublisherTCEntry added in v0.3.0 

func (r *ConsentReader) ReadPublisherTCEntry() (*PublisherTCEntry, error)

ReadPublisherTCEntry reads in a publisher TC entry. It's assumed that the segment type bit has already been read, despite those bits being grouped together in the spec. This is done because the logic for the remaining bits differs based on the segment type.

func (*ConsentReader) ReadRangeEntries added in v0.2.0 

func (r *ConsentReader) ReadRangeEntries(n uint) ([]*RangeEntry, error)

ReadRangeEntries reads n range entries of 1 + 16 or 32 bits.

func (*ConsentReader) ReadRestrictionType added in v0.3.0 

func (r *ConsentReader) ReadRestrictionType() (RestrictionType, error)

ReadRestrictionType reads two bits and returns an enum |RestrictionType|.

func (*ConsentReader) ReadSegmentType added in v0.3.0 

func (r *ConsentReader) ReadSegmentType() (SegmentType, error)

ReadSegmentType reads three bits and returns an enum |SegmentType|.

func (*ConsentReader) ReadString added in v0.2.0 

func (r *ConsentReader) ReadString(n uint) (string, error)

ReadString returns a string of length n by reading the next 6 * n bits.

func (*ConsentReader) ReadTime added in v0.2.0 

func (r *ConsentReader) ReadTime() (time.Time, error)

ReadTime reads the next 36 bits representing the epoch time in deciseconds and converts it to a time.Time.

func (*ConsentReader) ReadVendors added in v0.3.0 

func (r *ConsentReader) ReadVendors(t SegmentType) (*OOBVendorList, error)

ReadVendors reads in a vendor list representing either disclosed or allowed vendor lists. It's assumed that the segment type bit has already been read, despite those bits being grouped together in the spec. This is done because the logic for the remaining bits differs based on the segment type.

type GppHeader added in v0.5.0 

type GppHeader struct {
	Type     int
	Version  int
	Sections []int
}

GppHeader is the first section of a GPP Consent String. See ParseGppHeader for in-depth format.

func ParseGppHeader added in v0.5.0 

func ParseGppHeader(s string) (*GppHeader, error)

ParseGppHeader parses the first (and required) part of any GPP Consent String. It is used to read the Type, Version, and which sections are contained in the following string(s). Format is: Type Int(6) Fixed to 3 as “GPP Header field” Version Int(6) Version of the GPP spec (version 1, as of Jan. 2023) Sections Range(Fibonacci) List of Section IDs that are contained in the GPP string.

type GppParsedConsent added in v0.5.0 

type GppParsedConsent interface {
}

GppParsedConsent is an empty interface since GPP will need to handle more consent structs than just the Multi-state Privacy Agreement structs.

type GppSection added in v0.5.0 

type GppSection struct {
	// contains filtered or unexported fields
}

GppSection contains the specific Section ID (important to match up correct parsing). and pre-parsed Section Value, including all subsections.

func (*GppSection) GetSectionId added in v0.5.0 

func (g *GppSection) GetSectionId() int

GetSectionId returns the Section ID for a given GppSection.

type GppSectionParser added in v0.5.0 

type GppSectionParser interface {
	ParseConsent() (GppParsedConsent, error)
	GetSectionId() int
}

func MapGppSectionToParser added in v0.5.0 

func MapGppSectionToParser(s string) ([]GppSectionParser, error)

MapGppSectionToParser takes a base64 Raw URL Encoded string which represents a GPP v1 string of the format {gpp header}~{section 1}[.{sub-section}][~{section n}] and returns each pair of section value and parsing function that should be used. The pairs are returned to allow more control over how parsing functions are applied.

func NewMspa added in v0.5.2 

func NewMspa(sid int, section string) GppSectionParser

NewMspa returns a supported parser given a GPP Section ID. If the SID is not yet supported, it will be null.

type GppSubSection added in v0.5.0 

type GppSubSection struct {
	// Global Privacy Control (GPC) is signaled and set.
	Gpc bool
}

func ParseGppSubSections added in v0.5.0 

func ParseGppSubSections(subSections []string) (*GppSubSection, error)

ParseGppSubSections parses the subsections that may be appended to GPP sections after a `.` Currently, GPC is the only subsection, so we only have a single Subsection parsing function. In the future, Section IDs may need their own SubSection parser.

type GppSubSectionTypes added in v0.5.0 

type GppSubSectionTypes int
const (
	SubSectCore GppSubSectionTypes = iota
	SubSectGpc
)

type MspaConsent added in v0.5.0 

type MspaConsent int
const (
	ConsentNotApplicable MspaConsent = iota
	NoConsent
	Consent
	InvalidConsentValue
)

type MspaNaYesNo added in v0.5.0 

type MspaNaYesNo int

MspaNaYesNo represents common values for MSPA values representing answers, Not Applicable, Yes, No (in that order). 

const (
	MspaNotApplicable MspaNaYesNo = iota
	MspaYes
	MspaNo
	InvalidMspaValue
)

type MspaNotice added in v0.5.0 

type MspaNotice int
const (
	NoticeNotApplicable MspaNotice = iota
	NoticeProvided
	NoticeNotProvided
	InvalidNoticeValue
)

type MspaOptout added in v0.5.0 

type MspaOptout int
const (
	OptOutNotApplicable MspaOptout = iota
	OptedOut
	NotOptedOut
	InvalidOptOutValue
)

type MspaParsedConsent added in v0.5.0 

type MspaParsedConsent struct {
	// The version of this section specification used to encode the string.
	Version int
	// Notice of the Sharing of the Consumer’s Personal Data with Third Parties.
	// 0 Not Applicable. The Business does not share Personal Data with Third Parties.
	// 1 Yes, notice was provided
	// 2 No, notice was not provided
	SharingNotice MspaNotice
	// Notice of the Opportunity to Opt Out of the Sale of the Consumer’s Personal Data.
	// 0 Not Applicable. The Business does not Sell Personal Data.
	// 1 Yes, notice was provided
	// 2 No, notice was not provided
	SaleOptOutNotice MspaNotice
	// Notice of the Opportunity to Opt Out of the Sharing of the Consumer’s Personal Data.
	// 0 Not Applicable.The Business does not Share Personal Data.
	// 1 Yes, notice was provided
	// 2 No, notice was not provided
	SharingOptOutNotice MspaNotice
	// Notice of the Opportunity to Opt Out of Processing of the Consumer’s Personal Data for Targeted Advertising.
	// 0 Not Applicable.The Business does not Process Personal Data for Targeted Advertising.
	// 1 Yes, notice was provided
	// 2 No, notice was not provided
	TargetedAdvertisingOptOutNotice MspaNotice
	// Notice of the Opportunity to Opt Out of the Processing of the Consumer’s Sensitive Data.
	// 0 Not Applicable. The Business does not Process Sensitive Data.
	// 1 Yes, notice was provided
	// 2 No, notice was not provided
	SensitiveDataProcessingOptOutNotice MspaNotice
	// Notice of the Opportunity to Limit Use or Disclosure of the Consumer’s Sensitive Data.
	// 0 Not Applicable. The Business does not use or disclose Sensitive Data.
	// 1 Yes, notice was provided
	// 2 No, notice was not provided
	SensitiveDataLimitUseNotice MspaNotice
	// Opt-Out of the Sale of the Consumer’s Personal Data.
	// 0 Not Applicable. SaleOptOutNotice value was not applicable or no notice was provided
	// 1 Opted Out
	// 2 Did Not Opt Out
	SaleOptOut MspaOptout
	// Opt-Out of the Sharing of the Consumer’s Personal Data.
	// 0 Not Applicable. SharingOptOutNotice value was not applicable or no notice was provided.
	// 1 Opted Out
	// 2 Did Not Opt Out
	SharingOptOut MspaOptout
	// Opt-Out of Processing the Consumer’s Personal Data for Targeted Advertising.
	// 0 Not Applicable. TargetedAdvertisingOptOutNotice value was not applicable or no notice was provided
	// 1 Opted Out
	// 2 Did Not Opt Out
	TargetedAdvertisingOptOut MspaOptout
	// Two bits for each Data Activity:
	// 0 Not Applicable. The Business does not Process the specific category of Sensitive Data.
	// 1 No Consent
	// 2 Consent
	SensitiveDataProcessingConsents map[int]MspaConsent
	// Two bits for each Data Activity:
	// 0 Not Applicable. SensitiveDataLimitUseNotice value was not applicable or no notice was provided.
	// 1 Opted Out
	// 2 Did Not Opt Out
	SensitiveDataProcessingOptOuts map[int]MspaOptout
	// Two bits for each Data Activity:
	// 0 Not Applicable. The Business does not have actual knowledge that it Processes Personal Data or Sensitive Data of a Consumer who is a known child.
	// 1 No Consent
	// 2 Consent
	// Fields:
	// (1) Consent to Process the Consumer’s Personal Data or Sensitive Data for Consumers from Age 13 to 16.
	// (2) Consent to Process the Consumer’s Personal Data or Sensitive Data for Consumers Younger Than 13 Years of Age.
	KnownChildSensitiveDataConsents map[int]MspaConsent
	// Consent to Collection, Use, Retention, Sale, and/or Sharing of the Consumer’s Personal Data that Is Unrelated to or Incompatible with the Purpose(s) for which the Consumer’s Personal Data Was Collected or Processed.
	// 0 Not Applicable. The Business does not use, retain, Sell, or Share the Consumer’s Personal Data for advertising purposes that are unrelated to or incompatible with the purpose(s) for which the Consumer’s Personal Data was collected or processed.
	// 1 No Consent
	// 2 Consent
	PersonalDataConsents MspaConsent
	// Publisher or Advertiser, as applicable, is a signatory to the IAB Multistate Service Provider Agreement (MSPA), as may be amended from time to time, and declares that the transaction is a “Covered Transaction” as defined in the MSPA.
	// 1 Yes
	// 2 No
	MspaCoveredTransaction MspaNaYesNo
	// Publisher or Advertiser, as applicable, has enabled “Opt-Out Option Mode” for the “Covered Transaction,” as such terms are defined in the MSPA.
	// 0 Not Applicable.
	// 1 Yes
	// 2 No
	MspaOptOutOptionMode MspaNaYesNo
	// Publisher or Advertiser, as applicable, has enabled “Service Provider Mode” for the “Covered Transaction,” as such terms are defined in the MSPA.
	// 0 Not Applicable
	// 1 Yes
	// 2 No
	MspaServiceProviderMode MspaNaYesNo
	// Subsections added below:
	// Global Privacy Control (GPC) is signaled and set.
	Gpc bool
}

MspaParsedConsent represents data extract from a Multi-State Privacy Agreement (mspa) consent string. Format can be found here: https://github.com/InteractiveAdvertisingBureau/Global-Privacy-Platform/blob/main/Sections/US-National/IAB%20Privacy%E2%80%99s%20National%20Privacy%20Technical%20Specification.md#core-segment

type MspaUsCA added in v0.5.2 

type MspaUsCA struct {
	GppSection
}

func (*MspaUsCA) ParseConsent added in v0.5.2 

func (m *MspaUsCA) ParseConsent() (GppParsedConsent, error)

type MspaUsCO added in v0.5.2 

type MspaUsCO struct {
	GppSection
}

func (*MspaUsCO) ParseConsent added in v0.5.2 

func (m *MspaUsCO) ParseConsent() (GppParsedConsent, error)

type MspaUsCT added in v0.5.2 

type MspaUsCT struct {
	GppSection
}

func (*MspaUsCT) ParseConsent added in v0.5.2 

func (m *MspaUsCT) ParseConsent() (GppParsedConsent, error)

type MspaUsNational added in v0.5.0 

type MspaUsNational struct {
	GppSection
}

func (*MspaUsNational) ParseConsent added in v0.5.0 

func (m *MspaUsNational) ParseConsent() (GppParsedConsent, error)

type MspaUsUT added in v0.5.2 

type MspaUsUT struct {
	GppSection
}

func (*MspaUsUT) ParseConsent added in v0.5.2 

func (m *MspaUsUT) ParseConsent() (GppParsedConsent, error)

type MspaUsVA added in v0.5.1 

type MspaUsVA struct {
	GppSection
}

func (*MspaUsVA) ParseConsent added in v0.5.1 

func (m *MspaUsVA) ParseConsent() (GppParsedConsent, error)

type OOBVendorList added in v0.3.0 

type OOBVendorList struct {
	// Enum type.
	SegmentType SegmentType
	// The maximum Vendor ID that is included.
	MaxVendorID int
	// The encoding scheme used to encode the IDs in the section – Either a BitField Section or Range Section follows.
	// Encoding logic should choose the encoding scheme that results in the smaller output size for a given set.
	IsRangeEncoding bool

	// The value for each Vendor ID from 1 to MaxVendorId. Set the bit corresponding to a given Vendor ID to 1 if the
	// Publisher permits the vendor to use OOB legal bases.
	Vendors map[int]bool

	// Number of RangeEntry sections to follow.
	NumEntries int
	// A single or range of Vendor ID(s) of Vendor(s) who are allowed to use OOB legal bases on the given publisher’s
	// digital property. If a Vendor ID is not within the bounds of the ranges then they are not allowed to use OOB
	// legal bases on the given publisher's digital property.
	VendorEntries []*RangeEntry
}

OOBVendorList is represents either a DisclosedVendors or AllowedVendors list.

type ParsedConsent 

type ParsedConsent struct {
	Version           int
	Created           time.Time
	LastUpdated       time.Time
	CMPID             int
	CMPVersion        int
	ConsentScreen     int
	ConsentLanguage   string
	VendorListVersion int
	PurposesAllowed   map[int]bool
	MaxVendorID       int
	IsRangeEncoding   bool
	ConsentedVendors  map[int]bool
	DefaultConsent    bool
	NumEntries        int
	RangeEntries      []*RangeEntry
}

ParsedConsent represents data extracted from an IAB Consent String, v1.1.

func Parse deprecated 

func Parse(s string) (*ParsedConsent, error)

Parse takes a base64 Raw URL Encoded string which represents a Vendor Consent String and returns a ParsedConsent with its fields populated with the values stored in the string.

Example Usage: 

var pc, err = iabconsent.Parse("BONJ5bvONJ5bvAMAPyFRAL7AAAAMhuqKklS-gAAAAAAAAAAAAAAAAAAAAAAAAAA")

Deprecated: Use ParseV1 to parse V1 consent strings.

func ParseV1 added in v0.3.0 

func ParseV1(s string) (*ParsedConsent, error)

ParseV1 takes a base64 Raw URL Encoded string which represents a TCF v1.1 string and returns a ParsedConsent with its fields populated with the values stored in the string.

Example Usage: 

var pc, err = iabconsent.ParseV1("BONJ5bvONJ5bvAMAPyFRAL7AAAAMhuqKklS-gAAAAAAAAAAAAAAAAAAAAAAAAAA")

func (*ParsedConsent) EveryPurposeAllowed added in v0.2.0 

func (p *ParsedConsent) EveryPurposeAllowed(ps []int) bool

EveryPurposeAllowed returns true iff every purpose number in ps exists in the ParsedConsent, otherwise false.

func (*ParsedConsent) PurposeAllowed 

func (p *ParsedConsent) PurposeAllowed(ps int) bool

PurposeAllowed returns true if the passed purpose number exists in the ParsedConsent, otherwise false.

func (*ParsedConsent) SuitableToProcess added in v0.4.0 

func (p *ParsedConsent) SuitableToProcess(ps []int, v int) bool

SuitableToProcess is the union of EveryPurposeAllowed(ps) and VendorAllowed(v). It's used to make possible an interface that can be used to check whether its legal to process v1 & v2 strings.

func (*ParsedConsent) VendorAllowed 

func (p *ParsedConsent) VendorAllowed(v int) bool

VendorAllowed returns true if the ParsedConsent contains affirmative consent for VendorID v.

type PubRestrictionEntry added in v0.3.0 

type PubRestrictionEntry struct {
	// The Vendor’s declared Purpose ID that the publisher has indicated that they are overriding.
	PurposeID int
	// The restriction type.
	RestrictionType RestrictionType
	// Number of RangeEntry sections to follow.
	NumEntries int
	// A single or range of Vendor ID(s) who the publisher has designated as restricted under the
	// Purpose ID in this PubRestrictionsEntry.
	RestrictionsRange []*RangeEntry
}

PubRestrictionEntry is made up of three parts: Purpose ID, Restriction Type and, List of Vendor IDs under that Purpose restriction.

type PublisherTCEntry added in v0.3.0 

type PublisherTCEntry struct {
	// Enum type
	SegmentType SegmentType
	// The user's consent value for each Purpose established on the legal basis of consent, for the publisher.
	// The Purposes are numerically identified and published in the Global Vendor List.
	PubPurposesConsent map[int]bool
	// The Purpose’s transparency requirements are met for each Purpose established on the legal basis of legitimate
	// interest and the user has not exercised their “Right to Object” to that Purpose. By default or if the user has
	// exercised their “Right to Object to a Purpose, the corresponding bit for that purpose is set to 0.
	PubPurposesLITransparency map[int]bool
	// The number of Custom Purposes.
	NumCustomPurposes int
	// The consent value for each CustomPurposeId from 1 to NumberCustomPurposes,
	CustomPurposesConsent map[int]bool
	// The legitimate Interest disclosure establishment value for each CustomPurposeId from 1 to NumberCustomPurposes.
	CustomPurposesLITransparency map[int]bool
}

PublisherTCEntry represents Publisher Purposes Transparency and Consent.

type RangeEntry added in v0.2.0 

type RangeEntry struct {
	StartVendorID int
	EndVendorID   int
}

RangeEntry defines an inclusive range of vendor IDs from StartVendorID to EndVendorID.

type RestrictionType added in v0.3.0 

type RestrictionType int

RestrictionType is an enum type of publisher restriction types. 

const (
	// Purpose Flatly Not Allowed by Publisher (regardless of Vendor declarations).
	PurposeFlatlyNotAllowed RestrictionType = iota
	// Require Consent (if Vendor has declared the Purpose IDs legal basis as Legitimate
	// Interest and flexible)
	RequireConsent
	// Require Legitimate Interest (if Vendor has declared the Purpose IDs legal basis as Consent and flexible).
	RequireLegitimateInterest
	// Undefined (not used).
	Undefined
)

type SegmentType added in v0.3.0 

type SegmentType int

SegmentType is an enum type of possible Out-of-Band (OOB) legal bases. 

const (
	// The core string.
	CoreString SegmentType = iota
	// The DisclosedVendors is a TC String segment that signals which vendors have been disclosed to a given user
	// by a CMP. This segment is required when saving a global-context TC String. When a CMP updates a globally-scoped
	// TC String, the CMP MUST retain the existing values and only add new disclosed Vendor IDs that had not been added
	// by other CMPs in prior interactions with this user.
	DisclosedVendors
	// Signals which vendors the publisher permits to use OOB legal bases.
	AllowedVendors
	// Publishers may need to establish transparency and consent for a set of personal data processing
	// purposes for their own use. For example, a publisher that wants to set a frequency-capping first-party
	// cookie should request user consent for Purpose 1 "Store and/or access information on a device" in
	// jurisdictions where it is required.
	//
	// The Publisher TC segment in the TC string represents publisher purposes transparency & consent signals
	// which is different than the other TC String segments; they are used to collect consumer purposes transparency
	// & consent for vendors. This segment supports the standard list of purposes defined by the TCF as well as
	// Custom Purposes defined by the publisher if they so choose.
	PublisherTC
)

type SpecialFeature added in v0.3.0 

type SpecialFeature int

SpecialFeature is an enum type for special features. The TCF Policies designates certain Features as “special” which means a CMP must afford the user a means to opt in to their use. These “Special Features” are published and numerically identified in the Global Vendor List separately from normal Features. 

const (
	InvalidSpecialFeature SpecialFeature = iota
	// Vendors can:
	// - Collect and process precise geolocation data in support of one or more purposes.
	// - N.B. Precise geolocation means that there are no restrictions on the precision of a user’s location;
	//   this can be accurate to within several meters.
	UsePreciseGeolocation
	// Vendors can:
	// - Create an identifier using data collected via actively scanning a device for specific characteristics, e.g.
	//   installed fonts or screen resolution.
	// - Use such an identifier to re-identify a device.
	ActivelyScanDevice
)

type SpecialPurpose added in v0.3.0 

type SpecialPurpose int

SpecialPurpose is an enum type for special purposes. 

const (
	InvalidSpecialPurpose SpecialPurpose = iota
	// To ensure security, prevent fraud and debug vendors can:
	// - Ensure data are securely transmitted
	// - Detect and prevent malicious, fraudulent, invalid, or illegal activity.
	// - Ensure correct and efficient operation of systems and processes, including to monitor and enhance the
	//    performance of systems and processes engaged in permitted purposes.
	// Vendors cannot:
	// - Conduct any other data processing operation allowed under a different purpose under this purpose
	EnsureSecurity
	// To deliver information and respond to technical requests vendors can:
	// - Use a user’s IP address to deliver an ad over the internet
	// - Respond to a user’s interaction with an ad by sending the user to a landing page
	// - Use a user’s IP address to deliver content over the internet
	// - Respond to a user’s interaction with content by sending the user to a landing page
	// - Use information about the device type and capabilities for delivering ads or content, for example, to deliver
	// the right size ad creative or video file in a format supported by the device
	// Vendors cannot:
	// - Conduct any other data processing operation allowed under a different purpose under this purpose
	TechnicallyDeliverAds
)

type TCFVersion added in v0.3.0 

type TCFVersion int

TCFVersion is an enum type used for easily identifying which version a consent string is. 

const (
	// InvalidTCFVersion represents an invalid version.
	InvalidTCFVersion TCFVersion = iota
	// V1 represents a TCF v1.1 string.
	V1
	// V2 represents a TCF v2 string.
	V2
)

func TCFVersionFromTCString added in v0.3.0 

func TCFVersionFromTCString(s string) TCFVersion

TCFVersionFromTCString allows the caller to pass any valid consent string to determine which parse method is appropriate to call or otherwise return InvalidTCFVersion (0).

type V2ParsedConsent added in v0.3.0 

type V2ParsedConsent struct {
	// Version number of the encoding format.
	Version int
	// Epoch deciseconds when this TC String was first created (should not be changed
	// unless a new TCString is created from scratch).
	Created time.Time
	// Epoch deciseconds when TC String was last updated (Must be updated any time a
	// value is changed).
	LastUpdated time.Time
	// Consent Management Platform ID that last updated the TC String.
	// A unique ID will be assigned to each Consent Management Platform.
	CMPID int
	// Consent Management Platform version of the CMP that last updated this TC String.
	// Each change to a CMP should increment their internally assigned version number as
	// a record of which version the user gave consent and transparency was established.
	CMPVersion int
	// CMP Screen number at which consent was given for a user with the CMP that last
	// updated this TC String. The number is a CMP internal designation and is CMPVersion
	// specific. The number is used for identifying on which screen a user gave consent
	// as a record.
	ConsentScreen int
	// Two-letter ISO 639-1 language code in which the CMP UI was presented.
	ConsentLanguage string
	// Number corresponds to the Global Vendor List (GVL) vendorListVersion.
	VendorListVersion int
	// Version of policy used within GVL.
	TCFPolicyVersion int
	// Whether the signals encoded in this TC String were from service-specific storage
	// (true) versus ‘global’ consensu.org shared storage (false).
	IsServiceSpecific bool
	// Setting this to 1 means that a publisher-run CMP – that is still IAB Europe
	// registered – is using customized Stack descriptions and not the standard stack
	// descriptions defined in the Policies. A CMP that services multiple publishers sets
	// this value to 0.
	UseNonStandardStacks bool
	// The TCF Policies designates certain Features as “special” which means a CMP must
	// afford the user a means to opt in to their use. These “Special Features” are
	// published and numerically identified in the Global Vendor List separately from
	// normal Features.
	SpecialFeaturesOptIn map[int]bool
	// The user’s consent value for each Purpose established on the legal basis of consent.
	// The Purposes are numerically identified and published in the Global Vendor List.
	// From left to right, Purpose 1 maps to the 0th bit, purpose 24 maps to the bit at
	// index 23. Special Purposes are a different ID space and not included in this field.
	PurposesConsent map[int]bool
	// The Purpose’s transparency requirements are met for each Purpose on the legal basis
	// of legitimate interest and the user has not exercised their “Right to Object” to that
	// Purpose. By default or if the user has exercised their “Right to Object” to a Purpose,
	// the corresponding bit for that Purpose is set to 0. From left to right, Purpose 1 maps
	// to the 0th bit, purpose 24 maps to the bit at index 23. Special Purposes are a
	// different ID space and not included in this field.
	PurposesLITransparency map[int]bool
	// CMPs can use the PublisherCC field to indicate the legal jurisdiction the publisher is
	// under to help vendors determine whether the vendor needs consent for Purpose 1. In a
	// globally-scoped TC string, this field must always have a value of 0. When a CMP
	// encounters a globally-scoped TC String with PurposeOneTreatment=1 then it is considered
	// invalid and the CMP must discard it and re-establish transparency and consent.
	PurposeOneTreatment bool
	// The country code of the country that determines legislation of reference. Commonly,
	// this corresponds to the country in which the publisher’s business entity is established.
	PublisherCC string

	// The maximum Vendor ID that is represented in the following bit field or range encoding.
	MaxConsentVendorID int
	// The encoding scheme used to encode the IDs in the section – Either a BitField Section or
	// Range Section follows. Encoding logic should choose the encoding scheme that results in
	// the smaller output size for a given set.
	IsConsentRangeEncoding bool
	// The consent value for each Vendor ID.
	ConsentedVendors map[int]bool
	// Number of RangeEntry sections to follow.
	NumConsentEntries int
	// A single or range of Vendor ID(s) who have received consent. If a Vendor ID is not within
	// the bounds of the ranges then the vendor is assumed to have “No Consent”.
	ConsentedVendorsRange []*RangeEntry

	// The maximum Vendor ID that is represented in the following bit field or range encoding.
	MaxInterestsVendorID int
	// The encoding scheme used to encode the IDs in the section – Either a BitField Section or
	// Range Section follows. Encoding logic should encode with the encoding scheme that results
	// in the smaller output size for a given set.
	IsInterestsRangeEncoding bool
	// The legitimate interest value for each Vendor ID from 1 to MaxVendorId. Set the bit
	// corresponding to a given vendor to 1 if the CMP has established transparency for a vendor's
	// legitimate interest disclosures. If a user exercises their “Right To Object” to a vendor’s
	// processing based on a legitimate interest, then that vendor’s bit must be set to 0.
	InterestsVendors map[int]bool
	// 	Number of RangeEntry sections to follow.
	NumInterestsEntries int
	// A single or range of Vendor ID(s) who have established transparency for their legitimate
	// interest disclosures with the user. If a Vendor ID is not within the bounds of the ranges
	// then they have not established that transparency.
	InterestsVendorsRange []*RangeEntry

	// Number of restriction records to follow.
	NumPubRestrictions int
	// Each Publisher Restriction Entry is made up of three parts: Purpose ID, Restriction Type and,
	// List of Vendor IDs under that Purpose restriction.
	PubRestrictionEntries []*PubRestrictionEntry

	// The DisclosedVendors is a TC String segment that signals which vendors have been disclosed
	// to a given user by a CMP.
	OOBDisclosedVendors *OOBVendorList
	// Signals which vendors the publisher permits to use OOB legal bases.
	OOBAllowedVendors *OOBVendorList
	// Publishers may need to establish transparency and consent for a set of personal data processing
	// purposes for their own use. For example, a publisher that wants to set a frequency-capping
	// first-party cookie should request user consent for Purpose 1 "Store and/or access information on
	// a device" in jurisdictions where it is required.
	//
	// The Publisher TC segment in the TC string represents publisher purposes transparency & consent
	// signals which is different than the other TC String segments; they are used to collect consumer
	// purposes transparency & consent for vendors. This segment supports the standard list of purposes
	// defined by the TCF as well as Custom Purposes defined by the publisher if they so choose.
	*PublisherTCEntry
}

V2ParsedConsent represents data extracted from an v2 TCF Consent String.

func ParseV2 added in v0.3.0 

func ParseV2(s string) (*V2ParsedConsent, error)

ParseV2 takes a base64 Raw URL Encoded string which represents a TCF v2 string and returns a ParsedConsent with its fields populated with the values stored in the string.

Example Usage: 

var pc, err = iabconsent.ParseV2("COvzTO5OvzTO5BRAAAENAPCoALIAADgAAAAAAewAwABAAlAB6ABBFAAA")

func (*V2ParsedConsent) EveryPurposeAllowed added in v0.3.1 

func (p *V2ParsedConsent) EveryPurposeAllowed(ps []int) bool

EveryPurposeAllowed returns true iff every purpose number in ps exists in the V2ParsedConsent, otherwise false. This explicitly checks that the vendor has opted in, and does not cover legitimate interest. This is vendor agnostic, and should not be used without checking if there are any Publisher Restrictions for a given vendor or vendors (which can be done with a call of p.PublisherRestricted).

func (*V2ParsedConsent) MinorVersion added in v0.5.3 

func (p *V2ParsedConsent) MinorVersion() (int, error)

MinorVersion of the V2 TCF string is not explicitly set as a value, so we return the minor version of the string based on specific values set. If there is a TCFPolicyVersion that is higher than what is currently known, we will return an error message, and a very high value. This allows callers to error on the unsupported TCFPolicyVersions, and/or use their highest supported minor version when handling strings. More specifically, we will apply the highest supported minor version when parsing, but the user as the ability to call MinorVersion() on its own to decide what to do if TCF Policy Version is higher.

func (*V2ParsedConsent) PublisherRestricted added in v0.4.0 

func (p *V2ParsedConsent) PublisherRestricted(ps []int, v int) bool

PublisherRestricted returns true if any purpose in |ps| is Flatly Not Allowed and |v| is covered by that restriction.

func (*V2ParsedConsent) PurposeAllowed added in v0.5.0 

func (p *V2ParsedConsent) PurposeAllowed(ps int) bool

PurposeAllowed returns true if the passed purpose number exists in the V2ParsedConsent, otherwise false.

func (*V2ParsedConsent) SuitableToProcess added in v0.4.0 

func (p *V2ParsedConsent) SuitableToProcess(ps []int, v int) bool

SuitableToProcess evaluates if its suitable for a vendor (with a set of required purposes allowed on the basis of consent) to process a given request.

func (*V2ParsedConsent) VendorAllowed added in v0.3.1 

func (p *V2ParsedConsent) VendorAllowed(v int) bool

VendorAllowed returns true if the ParsedConsent contains affirmative consent for VendorID |v|.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.