Package com.iabtcf.decoder

Interface TCString

public interface TCString

  • Method Summary

    Modifier and Type Method Description
    static TCString decode​(String consentString, DecoderOption... options)
    Decodes an iabtcf compliant encoded string.
    IntIterable getAllowedVendors()
    Part of the OOB segments expressing that a Vendor is using legal bases outside of the TCF to process personal data.
    int getCmpId()
    Consent Management Platform ID that last updated the TC String
    int getCmpVersion()
    Consent Management Platform version of the CMP that last updated this TC String
    String getConsentLanguage()
    Two-letter ISO 639-1 language code in which the CMP UI was presented.
    int getConsentScreen()
    CMP Screen number at which consent was given for a user with the CMP that last updated this TC String.
    Instant getCreated()
    Epoch deciseconds (0.1 of a second) when this TC String was first created
    IntIterable getCustomPurposesConsent()
    Part of the Publisher Transparency and Consent segment of a TC String that publishers may use to establish transparency with and receive consent from users for their own legal bases to process personal data or to share with vendors if they so choose.
    IntIterable getCustomPurposesLITransparency()
    Part of the Publisher Transparency and Consent segment of a TC String that publishers may use to establish transparency with and receive consent from users for their own legal bases to process personal data or to share with vendors if they so choose.
    boolean getDefaultVendorConsent()
    Default consent for VendorIds not covered by a RangeEntry.
    IntIterable getDisclosedVendors()
    Part of the OOB segments expressing that a Vendor is using legal bases outside of the TCF to process personal data.
    Instant getLastUpdated()
    Epoch deciseconds (0.1 of a second) when TC String was last updated
    String getPublisherCC()
    The country code of the country that determines legislation of reference.
    List<PublisherRestriction> getPublisherRestrictions()
    The restrictions of a vendor's data processing by a publisher within the context of the users trafficking their digital property.
    IntIterable getPubPurposesConsent()
    Part of the Publisher Transparency and Consent segment of a TC String that publishers may use to establish transparency with and receive consent from users for their own legal bases to process personal data or to share with vendors if they so choose.
    IntIterable getPubPurposesLITransparency()
    Part of the Publisher Transparency and Consent segment of a TC String that publishers may use to establish transparency with and receive consent from users for their own legal bases to process personal data or to share with vendors if they so choose.
    boolean getPurposeOneTreatment()
    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.
    IntIterable getPurposesConsent()
    The user’s consent value for each Purpose established on the legal basis of consent.
    IntIterable getPurposesLITransparency()
    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.
    IntIterable getSpecialFeatureOptIns()
    The TCF Policies designates certain Features as "special" which means a CMP must afford the user a means to opt in to their use.
    int getTcfPolicyVersion()
    From the corresponding field in the GVL that was used for obtaining consent.
    boolean getUseNonStandardStacks()
    Setting this to field to true 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 (Appendix A section E).
    IntIterable getVendorConsent()
    The vendor identifiers that have consent to process this users personal data.
    IntIterable getVendorLegitimateInterest()
    If a user exercises their "Right To Object" to a vendor’s processing based on a legitimate interest.
    int getVendorListVersion()
    Number corresponds to GVL vendorListVersion.
    int getVersion()
    Version number of the encoding format
    boolean isServiceSpecific()
    Whether the signals encoded in this TC String were from service-specific storage versus global consesu.org shared storage.

  • Method Details

    • decode

      static TCString decode​(String consentString, DecoderOption... options) throws IllegalArgumentException, ByteParseException, UnsupportedVersionException
      Decodes an iabtcf compliant encoded string.
      Throws:
      ByteParseException - if version field failed to parse
      UnsupportedVersionException - invalid version field
      IllegalArgumentException - if consentString is not in valid Base64 scheme

    • getVersion

      int getVersion()
      Version number of the encoding format
      Returns:
      the version number
      Throws:
      TCStringDecodeException
      Since:
      1.0

    • getCreated

      Instant getCreated()
      Epoch deciseconds (0.1 of a second) when this TC String was first created
      Returns:
      timestamp the record was first created
      Throws:
      TCStringDecodeException
      Since:
      1.0

    • getLastUpdated

      Instant getLastUpdated()
      Epoch deciseconds (0.1 of a second) when TC String was last updated
      Returns:
      timestamp record was last updated
      Throws:
      TCStringDecodeException
      Since:
      1.0

    • getCmpId

      int getCmpId()
      Consent Management Platform ID that last updated the TC String
      Returns:
      the Consent Management Platform ID
      Throws:
      TCStringDecodeException
      Since:
      1.0

    • getCmpVersion

      int getCmpVersion()
      Consent Management Platform version of the CMP that last updated this TC String
      Returns:
      version of the Consent Management Platform that updated this record
      Throws:
      TCStringDecodeException
      Since:
      1.0

    • getConsentScreen

      int getConsentScreen()
      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.
      Returns:
      the screen number identifier
      Throws:
      TCStringDecodeException
      Since:
      1.0

    • getConsentLanguage

      String getConsentLanguage()
      Two-letter ISO 639-1 language code in which the CMP UI was presented.
      Returns:
      the language string
      Throws:
      TCStringDecodeException
      Since:
      1.0

    • getVendorListVersion

      int getVendorListVersion()
      Number corresponds to GVL vendorListVersion. Version of the GVL used to create this TC String.
      Returns:
      the version number
      Throws:
      TCStringDecodeException
      Since:
      1.0

    • getPurposesConsent

      IntIterable getPurposesConsent()
      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. An alias for PurposesAllowed
      Returns:
      The integer values for each established Purpose.
      Throws:
      TCStringDecodeException
      Since:
      1.0

    • getVendorConsent

      IntIterable getVendorConsent()
      The vendor identifiers that have consent to process this users personal data. The vendor identifiers are published in the GVL.
      Returns:
      the vendor identifiers.
      Throws:
      TCStringDecodeException
      Since:
      1.0

    • getDefaultVendorConsent

      boolean getDefaultVendorConsent()
      Default consent for VendorIds not covered by a RangeEntry. VendorIds covered by a RangeEntry have a consent value the opposite of DefaultConsent. This field is not used by Transparency and Consent String v2.0 specifications and always returns false.
      Returns:
      all vendors that have consent to process this users personal data
      Throws:
      TCStringDecodeException
      Since:
      1.0

    • getTcfPolicyVersion

      int getTcfPolicyVersion()
      From the corresponding field in the GVL that was used for obtaining consent. A new policy version invalidates existing strings and requires CMPs to re-establish transparency and consent from users.
      Returns:
      version of policy used within GVL
      Throws:
      TCStringDecodeException
      Since:
      2.0

    • isServiceSpecific

      boolean isServiceSpecific()
      Whether the signals encoded in this TC String were from service-specific storage versus global consesu.org shared storage.
      Returns:
      if signals are service-specific or global
      Throws:
      TCStringDecodeException
      Since:
      2.0

    • getUseNonStandardStacks

      boolean getUseNonStandardStacks()
      Setting this to field to true 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 (Appendix A section E). A CMP that services multiple publishers sets this value to false.
      Returns:
      true if if the CMP used non-IAB standard stacks during consent gathering; false otherwise.
      Throws:
      TCStringDecodeException
      Since:
      2.0

    • getSpecialFeatureOptIns

      IntIterable getSpecialFeatureOptIns()
      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.
      Returns:
      the Special Features the Vendor may utilize when performing some declared Purposes processing.
      Throws:
      TCStringDecodeException
      Since:
      2.0

    • getPurposesLITransparency

      IntIterable getPurposesLITransparency()
      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 identifier for that Purpose is set to false.
      Returns:
      The purpose identifiers for which the legal basis of legitimate interest are established.
      Throws:
      TCStringDecodeException
      Since:
      2.0

    • getPurposeOneTreatment

      boolean getPurposeOneTreatment()
      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 false. When a CMP encounters a globally-scoped TC String with PurposeOneTreatment set to true then it is considered invalid and the CMP must discard it and re-establish transparency and consent.
      Returns:
      true if Purpose 1 was NOT disclosed; false otherwise.
      Throws:
      TCStringDecodeException
      Since:
      2.0

    • getPublisherCC

      String getPublisherCC()
      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.
      Returns:
      ISO 3166-1 alpha-2 country code
      Throws:
      TCStringDecodeException
      Since:
      2.0

    • getVendorLegitimateInterest

      IntIterable getVendorLegitimateInterest()
      If a user exercises their "Right To Object" to a vendor’s processing based on a legitimate interest.
      Returns:
      vendor identifiers that can process this user based on legitimate interest
      Throws:
      TCStringDecodeException
      Since:
      2.0

    • getPublisherRestrictions

      List<PublisherRestriction> getPublisherRestrictions()
      The restrictions of a vendor's data processing by a publisher within the context of the users trafficking their digital property.
      Returns:
      the list of publisher restrictions.
      Throws:
      TCStringDecodeException
      Since:
      2.0

    • getAllowedVendors

      IntIterable getAllowedVendors()
      Part of the OOB segments expressing that a Vendor is using legal bases outside of the TCF to process personal data.
      Returns:
      A list of Vendors that the publisher allows to use out-of-band legal bases.
      Throws:
      TCStringDecodeException
      Since:
      2.0

    • getDisclosedVendors

      IntIterable getDisclosedVendors()
      Part of the OOB segments expressing that a Vendor is using legal bases outside of the TCF to process personal data.
      Returns:
      A list of Vendors that disclosed to the user.
      Throws:
      TCStringDecodeException
      Since:
      2.0

    • getPubPurposesConsent

      IntIterable getPubPurposesConsent()
      Part of the Publisher Transparency and Consent segment of a TC String that publishers may use to establish transparency with and receive consent from users for their own legal bases to process personal data or to share with vendors if they so choose. 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.
      Returns:
      the consent value for each Purpose
      Throws:
      TCStringDecodeException
      Since:
      2.0

    • getPubPurposesLITransparency

      IntIterable getPubPurposesLITransparency()
      Part of the Publisher Transparency and Consent segment of a TC String that publishers may use to establish transparency with and receive consent from users for their own legal bases to process personal data or to share with vendors if they so choose. 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 identifier for that Purpose is set to false.
      Returns:
      The consent value for each Purpose where legitimate interest was established.
      Throws:
      TCStringDecodeException
      Since:
      2.0

    • getCustomPurposesConsent

      IntIterable getCustomPurposesConsent()
      Part of the Publisher Transparency and Consent segment of a TC String that publishers may use to establish transparency with and receive consent from users for their own legal bases to process personal data or to share with vendors if they so choose. Custom purposes will be defined by the publisher and displayed to a user in a CMP user interface.
      Returns:
      The established custom purpose consent values
      Throws:
      TCStringDecodeException
      Since:
      2.0

    • getCustomPurposesLITransparency

      IntIterable getCustomPurposesLITransparency()
      Part of the Publisher Transparency and Consent segment of a TC String that publishers may use to establish transparency with and receive consent from users for their own legal bases to process personal data or to share with vendors if they so choose.
      Returns:
      The custom purpose consent values with established legitimate interest disclosure.
      Throws:
      TCStringDecodeException