# How it works

All commands can be executed through the API function `__sdcmpapi`, and Sirdata CMP provides a list of standard commands described in the [IAB Tech Lab CMP JavaScript API](https://github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework/blob/master/TCFv2/IAB%20Tech%20Lab%20-%20CMP%20API%20v2.md).

If you are using a version compatible with the Transparency and Consent Framework (TCF) (this is the default), the commands can also be executed through the API function `__tcfapi`.

{% tabs %}
{% tab title="\_\_sdcmpapi" %}

```javascript
window.__sdcmpapi(command, version, callback, parameter);
```

{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="\_\_tcfapi" %}

```erlang
window.__tcfapi(command, version, callback, parameter);
```

{% endtab %}
{% endtabs %}

The `version` parameter is the TCF specification version (= 2).

<table data-header-hidden><thead><tr><th>Command</th><th width="169">Callback</th><th width="182">Parameter</th><th>Description</th></tr></thead><tbody><tr><td><strong>Command</strong></td><td><strong>Callback</strong></td><td><strong>Parameter</strong></td><td><strong>Description</strong></td></tr><tr><td><strong>ping</strong></td><td>function(PingReturn, success)</td><td>-</td><td>Returns information about the CMP loading status and the GDPR application mode.</td></tr><tr><td><strong>revokeUtiq</strong></td><td>function(success)</td><td><strong>-</strong></td><td><p>Remove the existing consent for the Utiq partner and the associated purpose. The associated signal and the CMP UI (in case of redisplay) are updated.<br></p><p>Returns true if Utiq and the associated purpose are part of the CMP configuration, and false otherwise.</p></td></tr><tr><td><strong>getVendorList</strong></td><td>function(GlobalVendorList, success)</td><td><strong>vendorListVersion (int) - optionnel</strong><br>Global Vendor List version to fetch. If undefined, the version used by Sirdata CMP is returned. If value is LATEST, the latest available version is returned. If value is invalid, GlobalVendorList will be null and <code>success</code> will be false.</td><td>Returns the Global Vendor List containing the purposes and vendors participating in the Transparency &#x26; Consent Framework.</td></tr><tr><td><strong>addEventListener</strong></td><td>function(TCData, success)</td><td>-</td><td><p>Add a JavaScript function to call with TC Data whenever a CMP event occurs.</p><p><a href="https://cmp.docs.sirdata.net/v/en/cmp-api/how-it-works#events">See the list of events</a></p></td></tr><tr><td><strong>removeEventListener</strong></td><td>function(success)</td><td><strong>listenerId (int)</strong><br>Listener ID to remove.</td><td>Remove a listener previously added with the addEventListener command.</td></tr></tbody></table>

### PingReturn <a href="#ping-return" id="ping-return"></a>

```erlang
{
    gdprApplies: *Boolean*,
    cmpLoaded: *Boolean*,
    cmpStatus: *String*,
    displayStatus: *String*,
    apiVersion: '2.0',
    cmpVersion: *Integer*,
    cmpId: *Integer*,
    gvlVersion: *Integer*,
    tcfPolicyVersion: *Integer*
}
```

### TCData <a href="#tc-data" id="tc-data"></a>

```erlang
{
    tcString: [base64url-encoded] *String*,
    addtlConsent: *String*,
    tcfPolicyVersion: *Integer*,
    cmpId: *Integer*,
    cmpVersion: *Integer*,
    gdprApplies: *Boolean*,
    evenStatus: *String*,
    cmpStatus: *String*,
    isServiceSpecific: *Boolean*,
    useNonStandardStacks: *Boolean*,
    publisherCC: *String*,
    purposeOneTreatment: *Boolean*,
    outOfBand: {
        allowedVendors: {
            *vendorId*: *Boolean*,
            ?
        },
        disclosedVendors: {
            *vendorId*: *Boolean*,
            ?
        }
    },
    purpose: {
        consents: {
            *purposeId*: *Boolean*,
            ?
        },
        legitimateInterests: {
            *purposeId*: *Boolean*,
            ?
        }
    },
    vendor: {
        consents: {
            *vendorId* : *Boolean*,
            ?
        },
        legitimateInterests: {
            *vendorId* : *Boolean*,
            ?
        }
    },
    specialFeatureOptins: {
        *specialFeatureId*: *Boolean*,
        ?
    },
    publisher: {
        consents: {
            *purposeId*: *Boolean*,
            ?
        },
        legitimateInterests: {
            *purposeId*: *Boolean*,
            ?
        },
        customPurpose: {
            consents: {
                *customPurposeId*: *Boolean*,
                ?
            },
            legitimateInterests: {
                *customPurposeId*: *Boolean*,
                ?
            }
        },
        restrictions: {
            *purposeId*: {
                *vendorId* : *Integer*,
                ?
            },
            ?
        }
    }
}
```

### GlobalVendorList <a href="#global-vendor-list" id="global-vendor-list"></a>

```erlang
{
    gvlSpecificationVersion: *Integer*,
    vendorListVersion: *Integer*,
    tcfPolicyVersion: *Integer*,
    lastUpdated: *String*,
    purposes: {
        *purposeId*: {
            id: *Integer*,
            name: *String*,
            description: *String*,
            descriptionLegal: *String*,
        },
        ?
    },
    specialPurposes: {
        *specialPurposeId*: {
            id: *Integer*,
            name: *String*,
            description: *String*,
            descriptionLegal: *String*,
        },
        ?
    },
    features: {
        *featureId*: {
            id: *Integer*,
            name: *String*,
            description: *String*,
            descriptionLegal: *String*,
        },
        ?
    },
    specialFeatures: {
        *specialFeatureId*: {
            id: *Integer*,
            name: *String*,
            description: *String*,
            descriptionLegal: *String*,
        },
        ?
    },
    stacks: {
        *stackId*: {
            id: *Integer*,
            name: *String*,
            description: *String*,
            purposes: [
                *Integer*,
                ?
            ],
            specialFeatures: [
                *Integer*,
                ?
            ],
        },
        ?
    },
    vendors: {
        *vendorId*: {
        {
            id: *Integer*,
            name: *String*,
            purposes: [
                *Integer*,
                ?
            ],
            legIntPurposes: [
                *Integer*,
                ?
            ],
            flexiblePurposes: [
                *Integer*,
                ?
            ],
            specialPurposes: [
                *Integer*,
                ?
            ],
            features: [
                *Integer*,
                ?
            ],
            specialFeatures: [
                *Integer*,
                ?
            ],
            policyUrl: *String*,
            usesCookies: *Boolean*,
            cookieMaxAgeSeconds: *Integer*,            
            usesNonCookieAccess: *Boolean*,
            deviceStorageDisclosureUrl: *String*
        },
        ?
    }
}
```

### Events

You will find in the table below the list of events that can be triggered by the CMP:

| **Event**              | **Description**                                                                                                                                                                                                                                  |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **tcloaded**           | This event status is triggered when the CMP is loaded, a valid TC String is available and the UI is not surfaced.                                                                                                                                |
| **cmpuishown**         | This event status is triggered when the UI is surfaced or re-surfaced. If there's no existing TC String for the user, the CMP creates a TC String with all legitimate interest signals set to `true` and all the consent signals set to `false`. |
| **useractioncomplete** | This event status is triggered whenever a user has confirmed or re-confirmed their choices and the updated TC String is ready to be surfaced.                                                                                                    |
| **cmpuiclosed**        | This event status is triggered when a user closes the surfaced UI by clicking on the close button (if enabled) and thus the current TC String is unmodified by the CMP.                                                                          |