Understanding the IAB’s Global Vendor List (GVL)

Challenge: Ensuring compliance in data processing activities while managing vendors and user consents.

Solution: Effectively integrating the Global Vendor List (GVL) within a Consent Management Platform (CMP)

Welcome to the second part of our series, “Mastering CMP and IAB TCF: a developer’s guide.” Today, we will focus on the Global Vendor List (GVL), which is essential for complying with the IAB’s Transparency and Consent Framework (TCF). This guide is designed to equip developers with the knowledge and tools they need to effectively manage vendor lists.

VendorList (GVL)

The Vendor List, commonly referred to as the Global Vendor List (GVL), is a comprehensive list of vendors (partners) that have registered with the IAB TCF. Each vendor is assigned a unique ID and is associated with specific purposes, features, and legal bases for processing personal data.

Why is the GVL important?

• Transparency: the GVL provides a transparent mechanism for informing users about the vendors and the purposes for which their data will be used.
• Compliance: utilizing the GVL ensures that your CMP is aligned with the IAB TCF standards, helping to maintain compliance with data protection regulations such as GDPR.
• User trust: transparency and compliance contribute to building trust with users, as they can make informed choices about their data.

Example vendor: Google Advertising Products

Let’s take “Google Advertising Products” as an example. This is a vendor that specializes in delivering personalized advertising and content, measuring ad performance, and conducting market research. When you visit a site with the TCF consent modal, you might see a brief description like this:

“Google Advertising Products uses data to show you relevant ads and content based on your online activity, measure the effectiveness of ads, and provide insights to improve products and services. They use cookies and other technologies to collect this data. Your consent is required for these activities.”

The key pieces of information presented are:

• Purpose of data processing: explaining in simple terms what the vendor does with your data, such as personalizing content and ads, measuring ad performance, etc.
• Technologies used: informing you that cookies and other technologies are used to collect data.
• Consent requirement: making it clear that your consent is needed for these data processing activities.

Understanding the vendor-list.json structure

The vendor-list.json is a structured file provided by the IAB to ensure transparency and compliance in online advertising. It contains detailed information about various vendors, their purposes for data processing, features, and other crucial elements. Understanding this structure is essential for developers working with Consent Management Platforms (CMPs) and the IAB’s Transparency and Consent Framework (TCF). Below is a brief overview of the key components.

1. Metadata

• gvlSpecificationVersion: the version of the Global Vendor List specification.
• vendorListVersion: the version number of the vendor list.
• tcfPolicyVersion: the version of the TCF policy that the vendor list adheres to.
• lastUpdated: the date and time when the vendor list was last updated.

2. Purposes

Detailed information about the various purposes for which data may be processed. Each purpose includes:

– id: a unique identifier.

– name: the name of the purpose.

– description: a description of the purpose.

– illustrations: examples or additional explanations related to the purpose.

3. Special purposes, features, and special features

Similar to purposes, these sections provide details about special purposes, features, and special features. Each entry includes an ID, name, description, and possible illustrations.

4. Stacks

Predefined collections of purposes and features that vendors may subscribe to. Each stack includes:

– id: a unique identifier.

– purposes: a list of purpose IDs associated with the stack.

– specialFeatures: a list of special feature IDs associated with the stack.

– name: the name of the stack.

– description: a description of the stack.

5. Data categories

Lists the categories of data that may be processed, each with:

– id: a unique identifier.

– name: the name of the data category.

– description: a description of the data category.

6. Vendors

Contains detailed information about each registered vendor, including:

– id: a unique identifier.

– name: the name of the vendor.

– purposes, legIntPurposes, flexiblePurposes, specialPurposes, features, specialFeatures: lists of IDs indicating the purposes, features, and legal bases associated with the vendor.

– cookieMaxAgeSeconds, usesCookies, cookieRefresh, usesNonCookieAccess: information about the vendor’s cookie usage and data access methods.

– dataRetention: details the data retention policies for the vendor.

– urls: links to the vendor’s privacy policy and legal interest claim, if applicable.

– dataDeclaration: a list of data declaration IDs associated with the vendor.

– deviceStorageDisclosureUrl: URL providing detailed information about the vendor’s device storage practices.

Utilizing the GVL in CMP

A Consent Management Platform (CMP) is essential for managing user consents and ensuring compliance with data protection regulations. By integrating the Global Vendor List (GVL), the CMP can display detailed information about vendors and their data processing purposes, aiding users in making informed decisions. As users navigate through the CMP and make their choices, their consents are recorded based on the vendor and purpose IDs provided in the GVL.

Once the GVL file is fetched, you can use it to:

• Populate the CMP’s user interface with vendor and purpose information.
• Store user consents based on vendor and purpose IDs.
• Validate user consents against the GVL to ensure they are up to date.

Fetching and processing the vendor-list.json file

Setting up the endpoint

Registering a REST API endpoint in WordPress to generate the Klaro CMP configuration dynamically.

public function klaro_config_init() {
    register_rest_route('custom/v1', '/generate-tcf-config', array(
        'methods' => 'GET',
        'callback' => array($this, 'generate_klaro_config'),
        'permission_callback' => function () {
            return true;
        },
    ));
}

Fetching and processing the data

The function generate_klaro_config dynamically generates a Klaro Consent Manager configuration based on static and dynamic data sources. It fetches vendor information, maps it to various purposes and features, and then combines it with a static configuration template to produce a final JavaScript configuration that can be used on a website to manage user consent.

Load static configuration

The function starts by loading a static configuration from a local JSON file. This file contains predefined settings for the Klaro Consent Manager.

$staticConfig = json_decode(file_get_contents(ct_ultimate_gdpr_url('assets/tcf/config.json')), true);

Fetch dynamic vendor data

Next, it fetches dynamic vendor data from another JSON file. This data includes details about various vendors, their purposes, and the features they use.

$data = json_decode(file_get_contents(ct_ultimate_gdpr_url('assets/tcf/vendor-list.json')), true);

Prepare mappings and counts

The function then prepares mappings for purposes, special purposes, features, and data categories. It also counts the number of vendors associated with each purpose.

$featuresMapping = [];
foreach ($data['features'] as $feature) {
    $featuresMapping[$feature['id']] = $feature['name'];
}

$dataDeclarationMapping = [];
foreach ($data['dataCategories'] as $dataCategory) {
    $dataDeclarationMapping[$dataCategory['id']] = [
        'name' => $dataCategory['name'],
        'description' => $dataCategory['description']
    ];
}

$vendorsPurposeCount = [];

foreach ($data['vendors'] as $vendor) {
    foreach ($vendor['purposes'] as $purposeId) {
        if (!isset($vendorsPurposeCount[$purposeId])) {
            $vendorsPurposeCount[$purposeId] = 0;
        }
        $vendorsPurposeCount[$purposeId]++;
    }
}
$vendorCount = count($data['vendors']);

Generate dynamic services

A list of services is generated dynamically based on the vendor data. This includes creating detailed descriptions for each vendor, mapping them to their purposes, features, and other attributes, and formatting various sections of the descriptions for better readability and user interaction.

For each vendor, the function:

– fetches and formats privacy policy and legitimate interest claim links.

– lists and formats purposes, special purposes, features, and data declarations.

– adds details about consent expiry, tracking methods, and data retention policies.

– combines all these details to create a comprehensive description.

$pName = $p['name'];
$privacyPolicy = $p['urls'][0]['privacy'];
$legIntClaim = isset($p['urls'][0]['legIntClaim']) ? $p['urls'][0]['legIntClaim'] : null;

// Map purposes to their descriptions
$purposesConsent = array_map(function ($purposeId) use ($purposesMapping) {
    return $purposesMapping[$purposeId];
}, $p['purposes']);
 
$features = array_map(function ($featureId) use ($featuresMapping) {
    return $featuresMapping[$featureId];
}, $p['features']);

$seconds = isset($p['cookieMaxAgeSeconds']) ? $p['cookieMaxAgeSeconds'] : null;
$consentExpiry = null;

if ($seconds !== null) {
    $minutes = floor($seconds / 60);
    $hours = floor($minutes / 60);
    $days = floor($hours / 24);

    if ($days >= 1) {
        $consentExpiry = "$days days";
    } else {
        $consentExpiry = "$minutes minutes";
    }
}

Handle legitimate interest

Vendors with legitimate interest purposes are handled separately to ensure they are presented correctly in the consent manager.

$purposesLegitimateVendors = array_filter($services, function($service) {
    return strpos($service['name'], 've_') === 0 && isset($service['purposesLegitimate']) && $service['purposesLegitimate'] === true;
});

$purposesLegitimateVendorsModified = array_map(function($service) {
    $service['name'] = str_replace('ve_', 'veli_', $service['name']);
    $service['purposes'] = ['li_partners'];
    $service['default'] = false;
    return $service;
}, $purposesLegitimateVendors);

$services = array_merge($services, $purposesLegitimateVendorsModified);

Output JavaScript configuration

Finally, the function outputs the complete configuration as a JavaScript variable, setting the appropriate content type to ensure it is interpreted correctly by the browser.

$jsConfig = 'var klaroConfig = ' . json_encode($staticConfig) . ';';
header('Content-Type: text/javascript');
echo $jsConfig;
exit;

vendor-list.json in the Transparency and Consent Framework (TCF)

The consent modal, a critical component for obtaining user preferences in compliance with GDPR, is constructed using the data provided in the vendor-list.json file. This file supplies detailed information about various vendors, their purposes for data processing, and the features they utilize. When a user interacts with the consent modal, they are essentially navigating through options and making choices based on this vendor-specific information.

Once a user submits their preferences via the consent modal, these choices are saved locally in the user’s browser, typically in a cookie or browser storage. This local storage acts as a record of the user’s consent, ensuring that their preferences are respected in future interactions and that their data is processed according to their wishes. The stored consent information is then used to generate the TC String.

TC String

The locally saved preferences are not just a record; they play an active role in the user’s online experience. They are utilized to generate a Transparency and Consent String (TC String), a standardized format used to convey the user’s choices regarding data processing and advertising preferences across the digital advertising ecosystem.

The TC String is a compact, encoded string that efficiently represents the user’s consent decisions. It includes information about which vendors the user has consented to, the purposes for which their data can be used, and any special features or purposes that require explicit consent.

Differences between the TCF versions

There are multiple versions of TCF, each introducing changes and improvements over the previous ones. The main differences often revolve around how data is categorized, the granularity of user choices, and the transparency of information provided.

1. TCF v1.1: this was the initial version, focusing on providing a standardized approach to GDPR compliance.
2. TCF v2.0: introduced improvements in user transparency, choice granularity, and established a more comprehensive vendor list structure.
3. Later versions: subsequent versions continue to refine and enhance these aspects, ensuring alignment with evolving data protection regulations and industry standards.

Weekly updates and local copy

Fetching the vendor-list.json file from the IAB’s origin server ensures that you are accessing the most accurate and official version of the data.

The vendor-list.json file is updated weekly to reflect changes in vendor statuses, purposes, or other relevant information. It is crucial for advertisers and publishers to fetch the updated file regularly to ensure compliance and provide users with accurate and up-to-date information. It is recommended to keep a local copy of the file.

Conclusion

The GVL acts as a comprehensive directory, listing registered vendors along with their data processing purposes, features, and legal bases. By integrating the GVL within a Consent Management Platform (CMP), organizations can streamline the process of informing users, obtaining consents, and managing vendor interactions, all while adhering to the Transparency and Consent Framework (TCF) standards.

High-level overview of the structure and key elements of the vendor-list.json file:

{
  "properties": {
    "gvlSpecificationVersion": {"example": 3},
    "vendorListVersion": {"example": 23},
    "tcfPolicyVersion": {"example": 4},
    "lastUpdated": {"example": "2023-10-19T16:07:28Z"},
    "purposes": {
      "1": {
        "properties": {
          "id": {"example": 1},
          "name": {"example": "Store and/or access information..."},
          "description": {"example": "Cookies, device identifiers..."}
        }
      }
    },
    "specialPurposes": {
      "1": {
        "properties": {
          "id": {"example": 1},
          "name": {"example": "Ensure security, prevent fraud..."},
          "description": {"example": "Your data can be used to monitor..."}
        }
      }
    },
    "features": {
      "1": {
        "properties": {
          "id": {"example": 1},
          "name": {"example": "Match and combine data..."},
          "description": {"example": "Information about your activity..."}
        }
      }
    },
    "specialFeatures": {
      "1": {
        "properties": {
          "id": {"example": 1},
          "name": {"example": "Use precise geolocation data"},
          "description": {"example": "With your acceptance, your precise location..."}
        }
      }
    },
    "stacks": {
      "2": {
        "properties": {
          "id": {"example": 2},
          "purposes": {"items": {"example": 2}},
          "name": {"example": "Advertising based on limited data..."},
          "description": {"example": "Advertising can be presented based on limited data..."}
        }
      }
    },
    "dataCategories": {
      "1": {
        "properties": {
          "id": {"example": 1},
          "name": {"example": "IP addresses"},
          "description": {"example": "Your IP address is a number assigned..."}
        }
      }
    },
    "vendors": {
      "1": {
        "properties": {
          "id": {"example": 1},
          "name": {"example": "Exponential Interactive, Inc d/b/a VDX.tv"},
          "purposes": {"items": {"example": 1}},
          "specialPurposes": {"items": {"example": 1}},
          "features": {"items": {"example": 1}},
          "urls": {
            "items": {
              "properties": {
                "privacy": {"example": "https://vdx.tv/privacy/"},
                "legIntClaim": {"example": "https://cdnx.exponential.com/..."}
              }
            }
          },
          "dataDeclaration": {"items": {"example": 1}}
        }
      }
    }
  }
}

Purchase the most popular GDPR WordPress plugin tailored to Google Consent Mode v2. Remember to use only certified solutions. You can also find our GDPR & CCPA WordPress plugin on Codecanyon

Are you looking for a talented development team? Contact us.