iabtcfv2

package module
v1.2.0 Latest Latest
Warning

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

 Go to latest Published: Sep 12, 2023 License: GPL-3.0 Imports: 4 Imported by: 2

README

iab-tcf-v2

Go client library to read and encode IAB TCF v2.0 TC Strings.

Installation
go get github.com/SirDataFR/iabtcfv2

The package defines a TCData structure with the three segments a TC String can contain:

  • CoreString
  • DisclosedVendors
  • PublisherTC
Decode a TC String

To decode a TC String, use Decode(tcString string) (t *TCData, err error).

NOTE : A valid TC String must start with a Core String segment value.

var tcData, err = iabtcfv2.Decode("COxR03kOxR1CqBcABCENAgCMAP_AAH_AAAqIF3EXySoGY2thI2YVFxBEIYwfJxyigMgChgQIsSwNQIeFLBoGLiAAHBGYJAQAGBAEEACBAQIkHGBMCQAAgAgBiRCMQEGMCzNIBIBAggEbY0FACCVmHkHSmZCY7064O__QLuIJEFQMAkSBAIACLECIQwAQDiAAAYAlAAABAhIaAAgIWBQEeAAAACAwAAgAAABBAAACAAQAAICIAAABAAAgAiAQAAAAGgIQAACBABACRIAAAEANCAAgiCEAQg4EAo4AAA.IF3EXySoGY2tho2YVFzBEIYwfJxyigMgShgQIsS0NQIeFLBoGPiAAHBGYJAQAGBAkkACBAQIsHGBMCQABgAgRiRCMQEGMDzNIBIBAggkbY0FACCVmnkHS3ZCY70-6u__QA.elAAAAAAAWA")
if err != nil {
  fmt.Printf("%v", err)
}

To decode a segment value of a TC String, use the appropriate function:

  • DecodeCoreString(coreString string) (c *CoreString, err error)
  • DecodeDisclosedVendors(disclosedVendors string) (d *DisclosedVendors, err error)
  • DecodePublisherTC(publisherTC string) (p *PublisherTC, err error)
var coreString, err = iabtcfv2.DecodeCoreString("COxR03kOxR1CqBcABCENAgCMAP_AAH_AAAqIF3EXySoGY2thI2YVFxBEIYwfJxyigMgChgQIsSwNQIeFLBoGLiAAHBGYJAQAGBAEEACBAQIkHGBMCQAAgAgBiRCMQEGMCzNIBIBAggEbY0FACCVmHkHSmZCY7064O__QLuIJEFQMAkSBAIACLECIQwAQDiAAAYAlAAABAhIaAAgIWBQEeAAAACAwAAgAAABBAAACAAQAAICIAAABAAAgAiAQAAAAGgIQAACBABACRIAAAEANCAAgiCEAQg4EAo4AAA")
if err != nil {
  fmt.Printf("%v", err)
}

Use GetSegmentType(segment string) (segmentType SegmentType, err error) to read the segment type from a segment value:

  • SegmentTypeUndefined = undefined
  • SegmentTypeCoreString = Core String
  • SegmentTypeDisclosedVendors = Disclosed Vendors
  • SegmentTypePublisherTC = Publisher TC

You can find more information about segment types here.

Use GetVersion(s string) (version TcfVersion, err error) to read the cookie version from a TC String or a Core String segment value. This function also supports TCF v1.1 consent strings:

  • TcfVersionUndefined = undefined
  • TcfVersion1 = TCF v1.1
  • TcfVersion2 = TCF v2.0
Example
package main

import (
  "fmt"
  "github.com/SirDataFR/iabtcfv2"
)

func main() {
  tcString := "COxSKBCOxSKCCBcABCENAgCMAPzAAEPAAAqIDaQBQAMgAgABqAR0A2gDaQAwAMgAgANoAAA"
  
  version, err := iabtcfv2.GetVersion(tcString)
  if err != nil {
    fmt.Printf("%v", err)
  }
  
  segmentType, err := iabtcfv2.GetSegmentType(tcString)
  if err != nil {
    fmt.Printf("%v", err)
  }
  
  var tcData, err = iabtcfv2.Decode(tcString)
  if err != nil {
    fmt.Printf("%v", err)
  }
  
  fmt.Printf("%+v\n", version)
  fmt.Printf("%+v\n", segmentType)
  fmt.Printf("%+v\n", tcData.CoreString)
  fmt.Printf("%+v\n", tcData.DisclosedVendors)
  fmt.Printf("%+v\n", tcData.PublisherTC)
}
Encode a TC String

To encode a TC String, use ToTCString() string on the TCData structure.

To encode a single segment of a TC String, use Encode() string on the appropriate segment.

Example
package main

import (
  "fmt"
  "github.com/SirDataFR/iabtcfv2"
)

func main() {
  tcData := &TCData{
    CoreString: &CoreString{
      Version: 2,
      Created: time.Now(),
      LastUpdated: time.Now(),
      CmpId: 92,
      CmpVersion: 1,
      ConsentScreen: 1,
      ConsentLanguage: "EN",
      VendorListVersion: 32,
      TcfPolicyVersion: 2,
      PurposesConsent: map[int]bool{
        1:  true,
        2:  true,
        3:  true,
      },
    },
  }
  
  tcString := tcData.ToTCString()
  fmt.Printf("%v", tcString)
  
  segmentValue := tcData.CoreString.Encode()
  fmt.Printf("%v", segmentValue)
}
Read TC Data

To verify that a legal basis is established for a purpose or a vendor, use the functions on each structure.

CoreString
Function Parameter Description
IsSpecialFeatureAllowed int Returns true if user has given consent to special feature id
IsPurposeAllowed int Returns true if user has given consent to purpose id
IsPurposeLIAllowed int Returns true if legitimate interest is established for purpose id and user didn't exercise their right to object
IsVendorAllowed int Returns true if user has given consent to vendor id processing their personal data
IsVendorLIAllowed int Returns true if transparency for vendor id's legitimate interest is established and user didn't exercise their right to object
IsVendorAllowedForPurposes (int, ...int) Returns true if user has given consent to vendor id processing all purposes ids and publisher hasn't set restrictions for them
IsVendorAllowedForPurposesLI (int, ...int) Returns true if transparency for vendor id's legitimate interest is established for all purpose ids and publisher hasn't set restrictions for them
IsVendorAllowedForFlexiblePurposes (int, ...int) Returns true if user has given consent to vendor id processing all purposes ids or if transparency for its legitimate interest is established in accordance with publisher restrictions
IsVendorAllowedForFlexiblePurposesLI (int, ...int) Returns true if transparency for vendor id's legitimate interest is established for all purpose ids or if user has given consent in accordance with publisher restrictions
GetPubRestrictionsForPurpose int Returns a list of publisher restrictions applied to purpose id

NOTE: For convenience the CoreString functions are also available from the TCData structure.

DisclosedVendors
Function Parameter Description
IsVendorDisclosed int Returns true if vendor id is disclosed for validating OOB signaling
PublisherTC
Function Parameter Description
IsPurposeAllowed int Returns true if user has given consent to standard purpose id
IsPurposeLIAllowed int Returns true if legitimate interest is established for standard purpose id and user didn't exercise their right to object
IsCustomPurposeAllowed int Returns true if user has given consent to custom purpose id
IsCustomPurposeLIAllowed int Returns true if legitimate interest is established for custom purpose id and user didn't exercise their right to object
Example
package main

import (
  "fmt"
  "github.com/SirDataFR/iabtcfv2"
)

func main() {
  tcString := "COxSKBCOxSKCCBcABCENAgCMAPzAAEPAAAqIDaQBQAMgAgABqAR0A2gDaQAwAMgAgANoAAA.elAAAAAAAWA"
  
  var tcData, err = iabtcfv2.Decode(tcString)
  if err != nil {
    fmt.Printf("%v", err)
  }
  
  if tcData.IsPurposeAllowed(1) {
    fmt.Printf("user has given consent to purpose 1")
  }
  
  if tcData.IsVendorAllowed(53) {
    fmt.Printf("user has given consent to vendor 53")
  }
  
  if tcData.PublisherTC.IsPurposeAllowed(2) {
    fmt.Printf("user has given consent to publisher purpose 2")
  }
}

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Bits 

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

type CoreString 

type CoreString struct {
	Version                int
	Created                time.Time
	LastUpdated            time.Time
	CmpId                  int
	CmpVersion             int
	ConsentScreen          int
	ConsentLanguage        string
	VendorListVersion      int
	TcfPolicyVersion       int
	IsServiceSpecific      bool
	UseNonStandardTexts    bool
	SpecialFeatureOptIns   map[int]bool
	PurposesConsent        map[int]bool
	PurposesLITransparency map[int]bool
	PurposeOneTreatment    bool
	PublisherCC            string
	MaxVendorId            int
	IsRangeEncoding        bool
	VendorsConsent         map[int]bool
	NumEntries             int
	RangeEntries           []*RangeEntry
	MaxVendorIdLI          int
	IsRangeEncodingLI      bool
	VendorsLITransparency  map[int]bool
	NumEntriesLI           int
	RangeEntriesLI         []*RangeEntry
	NumPubRestrictions     int
	PubRestrictions        []*PubRestriction
}

func DecodeCoreString 

func DecodeCoreString(coreString string) (c *CoreString, err error)

Decodes a Core String value and returns it as a CoreString structure

func (*CoreString) Encode 

func (c *CoreString) Encode() string

Returns structure as a base64 raw url encoded string

func (*CoreString) GetPubRestrictionsForPurpose added in v1.0.3 

func (c *CoreString) GetPubRestrictionsForPurpose(id int) []*PubRestriction

Returns a list of publisher restrictions applied to purpose id

func (*CoreString) IsPurposeAllowed 

func (c *CoreString) IsPurposeAllowed(id int) bool

Returns true if user has given consent to purpose id

func (*CoreString) IsPurposeLIAllowed 

func (c *CoreString) IsPurposeLIAllowed(id int) bool

Returns true if legitimate interest is established for purpose id and user didn't exercise their right to object

func (*CoreString) IsSpecialFeatureAllowed 

func (c *CoreString) IsSpecialFeatureAllowed(id int) bool

Returns true if user has given consent to special feature id

func (*CoreString) IsVendorAllowed 

func (c *CoreString) IsVendorAllowed(id int) bool

Returns true if user has given consent to vendor id processing their personal data

func (*CoreString) IsVendorAllowedForFlexiblePurposes added in v1.1.0 

func (c *CoreString) IsVendorAllowedForFlexiblePurposes(id int, purposeIds ...int) bool

Returns true if user has given consent to vendor id processing all purposes ids or if transparency for its legitimate interest is established in accordance with publisher restrictions

func (*CoreString) IsVendorAllowedForFlexiblePurposesLI added in v1.1.0 

func (c *CoreString) IsVendorAllowedForFlexiblePurposesLI(id int, purposeIds ...int) bool

Returns true if transparency for vendor id's legitimate interest is established for all purpose ids or if user has given consent in accordance with publisher restrictions

func (*CoreString) IsVendorAllowedForPurposes added in v1.0.3 

func (c *CoreString) IsVendorAllowedForPurposes(id int, purposeIds ...int) bool

Returns true if user has given consent to vendor id processing all purposes ids and publisher hasn't set restrictions for them

func (*CoreString) IsVendorAllowedForPurposesLI added in v1.0.3 

func (c *CoreString) IsVendorAllowedForPurposesLI(id int, purposeIds ...int) bool

Returns true if transparency for vendor id's legitimate interest is established for all purpose ids and publisher hasn't set restrictions for them

func (*CoreString) IsVendorLIAllowed 

func (c *CoreString) IsVendorLIAllowed(id int) bool

Returns true if transparency for vendor id's legitimate interest is established and user didn't exercise their right to object

type DisclosedVendors 

type DisclosedVendors struct {
	SegmentType      int
	MaxVendorId      int
	IsRangeEncoding  bool
	DisclosedVendors map[int]bool
	NumEntries       int
	RangeEntries     []*RangeEntry
}

func DecodeDisclosedVendors 

func DecodeDisclosedVendors(disclosedVendors string) (d *DisclosedVendors, err error)

Decodes a Disclosed Vendors value and returns it as a DisclosedVendors structure

func (*DisclosedVendors) Encode 

func (d *DisclosedVendors) Encode() string

Returns structure as a base64 raw url encoded string

func (*DisclosedVendors) IsVendorDisclosed 

func (d *DisclosedVendors) IsVendorDisclosed(id int) bool

Returns true if vendor id is disclosed for validating OOB signaling

type PubRestriction 

type PubRestriction struct {
	PurposeId       int
	RestrictionType RestrictionType
	NumEntries      int
	RangeEntries    []*RangeEntry
}

func (*PubRestriction) IsVendorIncluded added in v1.0.3 

func (p *PubRestriction) IsVendorIncluded(id int) bool

Returns true if restriction is applied to vendor id

type PublisherTC 

type PublisherTC struct {
	SegmentType                  int
	PubPurposesConsent           map[int]bool
	PubPurposesLITransparency    map[int]bool
	NumCustomPurposes            int
	CustomPurposesConsent        map[int]bool
	CustomPurposesLITransparency map[int]bool
}

func DecodePublisherTC 

func DecodePublisherTC(publisherTC string) (p *PublisherTC, err error)

Decodes a Publisher TC value and returns it as a PublisherTC structure

func (*PublisherTC) Encode 

func (p *PublisherTC) Encode() string

Returns structure as a base64 raw url encoded string

func (*PublisherTC) IsCustomPurposeAllowed 

func (p *PublisherTC) IsCustomPurposeAllowed(id int) bool

Returns true if user has given consent to custom purpose id

func (*PublisherTC) IsCustomPurposeLIAllowed 

func (p *PublisherTC) IsCustomPurposeLIAllowed(id int) bool

Returns true if legitimate interest is established for custom purpose id and user didn't exercise their right to object

func (*PublisherTC) IsPurposeAllowed 

func (p *PublisherTC) IsPurposeAllowed(id int) bool

Returns true if user has given consent to standard purpose id

func (*PublisherTC) IsPurposeLIAllowed 

func (p *PublisherTC) IsPurposeLIAllowed(id int) bool

Returns true if legitimate interest is established for standard purpose id and user didn't exercise their right to object

type RangeEntry 

type RangeEntry struct {
	StartVendorID int
	EndVendorID   int
}

type RestrictionType added in v1.0.3 

type RestrictionType int
const (
	RestrictionTypeNotAllowed     RestrictionType = 0
	RestrictionTypeRequireConsent RestrictionType = 1
	RestrictionTypeRequireLI      RestrictionType = 2
	RestrictionTypeUndefined      RestrictionType = 3
)

type SegmentType added in v1.0.2 

type SegmentType int
const (
	SegmentTypeUndefined        SegmentType = -1
	SegmentTypeCoreString       SegmentType = 0
	SegmentTypeDisclosedVendors SegmentType = 1
	SegmentTypePublisherTC      SegmentType = 3
)

func GetSegmentType added in v1.0.2 

func GetSegmentType(segment string) (segmentType SegmentType, err error)

Decodes a segment value and returns the SegmentType - SegmentTypeUndefined = -1 - SegmentTypeCoreString = 0 - SegmentTypeDisclosedVendors = 1 - SegmentTypePublisherTC = 3

type TCData 

type TCData struct {
	CoreString       *CoreString
	DisclosedVendors *DisclosedVendors
	PublisherTC      *PublisherTC
}

func Decode 

func Decode(tcString string) (t *TCData, err error)

Decode a TC String and returns it as a TCData structure A valid TC String must start with a Core String segment A TC String can optionally and arbitrarily ordered contain: - Disclosed Vendors - Publisher TC

func (*TCData) GetPubRestrictionsForPurpose added in v1.0.3 

func (t *TCData) GetPubRestrictionsForPurpose(id int) []*PubRestriction

Returns a list of publisher restrictions applied to purpose id

func (*TCData) IsPurposeAllowed 

func (t *TCData) IsPurposeAllowed(id int) bool

Returns true if user has given consent to purpose id

func (*TCData) IsPurposeLIAllowed 

func (t *TCData) IsPurposeLIAllowed(id int) bool

Returns true if legitimate interest is established for purpose id and user didn't exercise their right to object

func (*TCData) IsSpecialFeatureAllowed added in v1.0.2 

func (t *TCData) IsSpecialFeatureAllowed(id int) bool

Returns true if user has given consent to special feature id

func (*TCData) IsVendorAllowed 

func (t *TCData) IsVendorAllowed(id int) bool

Returns true if user has given consent to vendor id processing their personal data

func (*TCData) IsVendorAllowedForFlexiblePurposes added in v1.1.0 

func (t *TCData) IsVendorAllowedForFlexiblePurposes(id int, purposeIds ...int) bool

Returns true if user has given consent to vendor id processing all purposes ids or if transparency for its legitimate interest is established in accordance with publisher restrictions

func (*TCData) IsVendorAllowedForFlexiblePurposesLI added in v1.1.0 

func (t *TCData) IsVendorAllowedForFlexiblePurposesLI(id int, purposeIds ...int) bool

Returns true if transparency for vendor id's legitimate interest is established for all purpose ids or if user has given consent in accordance with publisher restrictions

func (*TCData) IsVendorAllowedForPurposes added in v1.0.3 

func (t *TCData) IsVendorAllowedForPurposes(id int, purposeIds ...int) bool

Returns true if user has given consent to vendor id processing all purposes ids and publisher hasn't set restrictions for them

func (*TCData) IsVendorAllowedForPurposesLI added in v1.0.3 

func (t *TCData) IsVendorAllowedForPurposesLI(id int, purposeIds ...int) bool

Returns true if transparency for vendor id's legitimate interest is established for all purpose ids and publisher hasn't set restrictions for them

func (*TCData) IsVendorLIAllowed 

func (t *TCData) IsVendorLIAllowed(id int) bool

Returns true if transparency for vendor id's legitimate interest is established and user didn't exercise their right to object

func (*TCData) ToTCString 

func (t *TCData) ToTCString() string

Returns structure as a base64 raw url encoded string

type TCEncoder 

type TCEncoder struct {
	*Bits
}

type TcfVersion added in v1.0.2 

type TcfVersion int
const (
	TcfVersionUndefined TcfVersion = -1
	TcfVersion1         TcfVersion = 1
	TcfVersion2         TcfVersion = 2
)

func GetVersion added in v1.0.2 

func GetVersion(s string) (version TcfVersion, err error)

Decodes a string and returns the TcfVersion It can also decode version from a TCF V1.1 consent string - TcfVersionUndefined = -1 - TcfVersion1 = 1 - TcfVersion2 = 2

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.