iabconsent

package module
v1.0.6 Latest Latest
Warning

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

 Go to latest Published: Jun 26, 2023 License: MIT Imports: 7 Imported by: 0

README

iabconsent

Build Status

Go Report Card

A Golang implementation of the IAB Consent String 1.1 Spec as well as the IAB Transparency and Consent String v2.0.

To install:

go get -v github.com/LiveRamp/iabconsent

This package defines a two structs (ParsedConsent and V2ParsedConsent) which contain all of the fields of the IAB 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/StackAdapt/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.

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 (
	CCPAYes           = 'Y'
	CCPANo            = 'N'
	CCPANotApplicable = '-'
	CCPAVersion       = 1
)
View Source 
const (
	SectionIDEUTCFv2 = 2
	SectionIDCANTCF  = 5
	SectionIDUSPV1   = 6
	SectionIDUSNAT   = 7
	SectionIDUSCA    = 8
	SectionIDUSVA    = 9
	SectionIDUSCO    = 10
	SectionIDUSUT    = 11
	SectionIDUSCT    = 12
)

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 

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 IsValidCCPAString 

func IsValidCCPAString(ccpaString string) (bool, error)

func ParseGpcSubsection 

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 

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 CcpaParsedConsent 

type CcpaParsedConsent struct {
	// The version of this string specification used to encode the string
	Version int

	// N = No, Y = Yes, - = Not Applicable
	Notice uint8

	// N = No, Y = Yes, - = Not Applicable; For use ONLY when CCPA does not apply.
	OptOutSale uint8

	// 0 = No, 1 = Yes, - = Not Applicable
	LSPACoveredTransaction uint8
}

CcpaParsedConsent represents data extract from a California Consumer Privacy Act (CCPA) consent string. Format can be found here: https://github.com/InteractiveAdvertisingBureau/USPrivacy/blob/master/CCPA/US%20Privacy%20String.md

func ParseCCPA 

func ParseCCPA(s string) (*CcpaParsedConsent, error)

type ConsentReader 

type ConsentReader struct {
	*bits.Reader
}

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

func NewConsentReader 

func NewConsentReader(src []byte) *ConsentReader

NewConsentReader returns a new ConsentReader backed by src.

func (*ConsentReader) ReadBitField 

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 

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 

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 

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

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

func (*ConsentReader) ReadMspaBitfieldConsent 

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) ReadMspaConsent 

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 

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 

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 

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 

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 

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

ReadPubRestrictionEntries reads n publisher restriction entries.

func (*ConsentReader) ReadPublisherTCEntry 

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 

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

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

func (*ConsentReader) ReadRestrictionType 

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

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

func (*ConsentReader) ReadSegmentType 

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

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

func (*ConsentReader) ReadString 

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 

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 

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 

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 

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 

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 

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 

func (g *GppSection) GetSectionId() int

GetSectionId returns the Section ID for a given GppSection.

func (*GppSection) GetSectionValue 

func (g *GppSection) GetSectionValue() string

GetSectionValue returns the Section Value for a given GppSection.

type GppSectionParser 

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

func MapGppSectionToParser 

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.

type GppSubSection 

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

func ParseGppSubSections 

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 

type GppSubSectionTypes int
const (
	SubSectCore GppSubSectionTypes = iota
	SubSectGpc
)

type MspaConsent 

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

type MspaNaYesNo 

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 

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

type MspaOptout 

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

type MspaParsedConsent 

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
	// Data Activities:
	// (1) Consent to Process the Consumer’s Sensitive Data Consisting of Personal Data Revealing Racial or Ethnic Origin.
	// (2) Consent to Process the Consumer’s Sensitive Data Consisting of Personal Data Revealing Religious or Philosophical Beliefs.
	// (3) Consent to Process the Consumer’s Sensitive Data Consisting of Personal Data Concerning a Consumer’s Health (including a Mental or Physical Health Condition or Diagnosis; Medical History; or Medical Treatment or Diagnosis by a Health Care Professional).
	// (4) Consent to Process the Consumer’s Sensitive Data Consisting of Personal Data Revealing Sex Life or Sexual Orientation.
	// (5) Consent to Process the Consumer’s Sensitive Data Consisting of Personal Data Revealing Citizenship or Immigration Status.
	// (6) Consent to Process the Consumer’s Sensitive Data Consisting of Genetic Data for the Purpose of Uniquely Identifying an Individual / Natural Person.
	// (7) Consent to Process the Consumer’s Sensitive Data Consisting of Biometric Data for the Purpose of Uniquely Identifying an Individual / Natural Person.
	// (8) Consent to Process the Consumer’s Sensitive Data Consisting of Precise Geolocation Data.
	// (9) Consent to Process the Consumer’s Sensitive Data Consisting of a Consumer’s Social Security, Driver’s License, State Identification Card, or Passport Number.
	// (10) Consent to Process the Consumer’s Sensitive Data Consisting of a Consumer’s Account Log-In, Financial Account, Debit Card, or Credit Card Number in Combination with Any Required Security or Access Code, Password, or Credentials Allowing Access to an Account.
	// (11) Consent to Process the Consumer’s Sensitive Data Consisting of Union Membership.
	// (12) Consent to Process the Consumer’s Sensitive Data Consisting of the contents of a Consumer’s Mail, Email, and Text Messages unless You Are the Intended Recipient of the Communication.
	SensitiveDataProcessing map[int]MspaConsent
	// 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 

type MspaUsCA struct {
	GppSection
}

func NewMspaCA 

func NewMspaCA(section string) *MspaUsCA

func (*MspaUsCA) ParseConsent 

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

type MspaUsCO 

type MspaUsCO struct {
	GppSection
}

func NewMspaCO 

func NewMspaCO(section string) *MspaUsCO

func (*MspaUsCO) ParseConsent 

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

type MspaUsCT 

type MspaUsCT struct {
	GppSection
}

func NewMspaCT 

func NewMspaCT(section string) *MspaUsCT

func (*MspaUsCT) ParseConsent 

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

type MspaUsNational 

type MspaUsNational struct {
	GppSection
}

func NewMspaNational 

func NewMspaNational(section string) *MspaUsNational

func (*MspaUsNational) ParseConsent 

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

type MspaUsUT 

type MspaUsUT struct {
	GppSection
}

func NewMspaUT 

func NewMspaUT(section string) *MspaUsUT

func (*MspaUsUT) ParseConsent 

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

type MspaUsVA 

type MspaUsVA struct {
	GppSection
}

func NewMspaVA 

func NewMspaVA(section string) *MspaUsVA

func (*MspaUsVA) ParseConsent 

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

type NotSupported 

type NotSupported struct {
	GppSection
}

func NewNotSupported 

func NewNotSupported(section string, sectionID int) *NotSupported

func (*NotSupported) ParseConsent 

func (n *NotSupported) ParseConsent() (GppParsedConsent, error)

type OOBVendorList 

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 

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 

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 

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 

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 

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 

type RangeEntry struct {
	StartVendorID int
	EndVendorID   int
}

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

type RestrictionType 

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 

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 

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 

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 TCFCA 

type TCFCA struct {
	GppSection
}

func NewTCFCA 

func NewTCFCA(section string) *TCFCA

func (*TCFCA) ParseConsent 

func (t *TCFCA) ParseConsent() (GppParsedConsent, error)

type TCFEU 

type TCFEU struct {
	GppSection
}

func NewTCFEU 

func NewTCFEU(section string) *TCFEU

func (*TCFEU) ParseConsent 

func (t *TCFEU) ParseConsent() (GppParsedConsent, error)

type TCFVersion 

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 

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 USPV 

type USPV struct {
	GppSection
}

func NewUSPV 

func NewUSPV(section string) *USPV

func (*USPV) ParseConsent 

func (u *USPV) ParseConsent() (GppParsedConsent, error)

type V2CAParsedConsent 

type V2CAParsedConsent 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
	// 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.
	SpecialFeatureExpressConsent 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.
	PurposesExpressConsent 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.
	PurposesImpliedConsent map[int]bool

	MaxExpressConsentVendorID     int
	IsExpressConsentRangeEncoding bool
	// The consent value for each Vendor ID.
	ExpressConsentedVendors map[int]bool
	// Number of RangeEntry sections to follow.
	NumExpressConsentEntries 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”.
	VendorExpressConsent []*RangeEntry

	MaxImpliedConsentVendorID     int
	IsImpliedConsentRangeEncoding bool
	// The consent value for each Vendor ID.
	ImpliedConsentedVendors map[int]bool
	// Number of RangeEntry sections to follow.
	NumImpliedConsentEntries 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”.
	VendorImpliedConsent []*RangeEntry

	*PublisherTCEntry
}

V2CAParsedConsent represents data extracted from an v2 CA TCF Consent String.

func ParseCAV2 

func ParseCAV2(s string) (*V2CAParsedConsent, error)

type V2ParsedConsent 

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 

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 

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) PublisherRestricted 

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 

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

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

func (*V2ParsedConsent) SuitableToProcess 

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 

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.