Ketch Headless Implementation

Ketch's headless implementation provides APIs to allow customers to create custom experiences, while still leveraging the content stored within the Ketch Platform.

With a headless experience server you will develop support for:

  1. Displaying user's consent and/or marketing preferences status
  2. Setting / updating consent and/or marketing preferences status
  3. Offering users the ability to invoke applicable subject rights (e.g. Delete my data)

The following APIs are used for Ketch's headless implementation:

Get the configuration

The Ketch configuration contains all the information needed to create your experience.

To get the configuration call the following API, replacing ORG_CODE and PROPERTY_CODE with their respective values.

GET https://global.ketchcdn.com/web/v2/config/ORG_CODE/PROPERTY_CODE/config.json

The result is a JSON object containing only the information needed to create the experience for the users current location. The location is determined by the users IP address when the call is made.

An example of the full configuration object can be found here.

The properties on the resulting JSON object needed to create the experience are experiences.preference and purposes.

Overriding users location and language

If you need to override the users location, one of the following query parameters can be used depending on what information you have available.

parameterallowed valuesdescription
regionISO-3166 country codelist of supported ISO 3166 ALPHA-2 country codes to show in the rights form
jurisdictionjurisdiction code defined in Ketch Platformthe code for the jurisdiction created within the Ketch Platform.

GET https://global.ketchcdn.com/web/v2/config/ORG_CODE/PROPERTY_CODE/config.json?region=US-CA

GET https://global.ketchcdn.com/web/v2/config/ORG_CODE/PROPERTY_CODE/config.json?jurisdiction=california

The configuration will contain the default language configured within the Ketch Platform. To get the configuration for a different language, use the following query parameter.

parameterallowed valuesdescription
languageISO 639-1 language code, with optional regional extensionoverrides default language to use a specific language

GET https://global.ketchcdn.com/web/v2/config/ORG_CODE/PROPERTY_CODE/config.json?language=fr

GET https://global.ketchcdn.com/web/v2/config/ORG_CODE/PROPERTY_CODE/config.json?language=fr-FR

Get current consent

To get the current consent for a user, use the following steps.

  1. Get the configuration for the current user as described above.
  2. Gather the identity values for the identity spaces defined within the configuration obtained above.
    {
    	...,
      "identities": {
          "swb_website_smart_tag": {
              "type": "managedCookie",
              "variable": "_swb"
          }
      },
      ...
    }
    
  3. Call the following API, replacing ORG_CODE, PROPERTY_CODE, JURISDICTION_CODE_FROM_CONFIG, and identities with their respective values.

POST https://global.ketchcdn.com/web/v2/consent/ORG_CODE/get

optional query parametersdescription
protocolsa comma separated list of privacy protocol strings to return. Supported values:

- tcfcav1
- tcfeuv2
- usca
- usco
- usct
- usut
- usva
(example: ?protocols=tcfcav1)

POST https://global.ketchcdn.com/web/v2/consent/ORG_CODE/get?protocols=tcfeuv2

{
    "organizationCode": "ORG_CODE",
    "propertyCode": "PROPERTY_CODE",
    "environmentCode": "production",
    "jurisdictionCode": "JURISDICTION_CODE_FROM_CONFIG",
    "identities": {
        "IDENTITY_1_CODE": "IDENTITY_1_VALUE",
        "IDENTITY_2_CODE": "IDENTITY_2_VALUE",
        ...
    },
    "protocols": "tcfeuv2"
}

The result will be a JSON object with users consent preferences for the jurisdiction specified in the request. This object will contain the following information:

propertyvalue description
environmentCodecode for the environment in which the consent was collected
identitiesJSON object with the identity space code as property names and property corresponding to relevant the identity space.
jurisdictionCodejurisdiction code in which the consent was collected.
propertyCodeproperty code as defined within the Ketch Platform on which the consent was collected
purposesJSON object with purpose codes as property names and a users consent choice (true/false) as the property value. If the user has not previously provide consent for a purpose, then you will not see the purpose code in the result.

ex: if there is a purpose defined for personalization and the result from the request does not contain a property code for personalization, this means consent has not been captured against the identities specified in the request.
vendorsA list of vendor identifiers for which the user has opted out
protocolsA json object with the protocol identifier as the key and the protocol string corresponding to the consent as the value.
{
    "environmentCode": "production",
    "identities": {
        "account_id": "120e710b-71c9-4134-a42g-f16541bff1c6"
    },
    "jurisdictionCode": "california_cpa",
    "propertyCode": "test",
    "purposes": {
        "analytics": "true",
        "data_sharing": "true",
        "personalization": "true",
        "targetedadvertising": "true"
    },
    "vendors": ["1", "2"],
    "protcols": {
        "tcfeuv2": "CPv736DPv736DFUABAENALEsAP_gAAAAACiQAAAAAAAA.YAAAAAAAAAA",
    }
}

Set consent

Once consent is gathered for the user, it needs to be sent to the Ketch Platform. Use the following API with corresponding body to send/update the users consent, replacing ORG_CODE, PROPERTY_CODE, JURISDICTION_CODE_FROM_CONFIG, and identities with their respective values.

The purposes object should contain a purpose object with the purpose code as the property name. The property should contain the following properties with their corresponding values.

purpose namedescription
allowedvalue depicting the users consent choice. true or false
legalBasisCodelegal basis code for which the purpose was collected. this can be found in the object returned from the configuration API call.

POST https://global.ketchcdn.com/web/v2/consent/ORG_CODE/update

query parametersvalue description
protocolsa comma separated list of privacy protocol strings to return. Supported values:

- tcfcav1
- tcfeuv2
- usca
- usco
- usct
- usut
- usva
(example: ?protocols=tcfcav1)

POST https://global.ketchcdn.com/web/v2/consent/ORG_CODE/update?protocols=tcfeuv2

{
    "organizationCode": "ORG_CODE",
    "propertyCode": "PROPERTY_CODE",
    "environmentCode": "production",
    "identities": {
        "IDENTITY_1_CODE": "IDENTITY_1_VALUE",
        "IDENTITY_2_CODE": "IDENTITY_2_VALUE",
        ...
    },
    "jurisdictionCode": "JURISDICTION_CODE_FROM_CONFIG",
    "purposes": {
        "PURPOSE_CODE_1": {
            "allowed": "false",
            "legalBasisCode": "consent_optout"
        },
        "PURPOSE_CODE_2": {
            "allowed": "false",
            "legalBasisCode": "consent_optout"
        },
        "PURPOSE_CODE_3": {
            "allowed": "false",
            "legalBasisCode": "consent_optout"
        },
        "PURPOSE_CODE_4": {
            "allowed": "true",
            "legalBasisCode": "consent_optout"
        }
    },
    "vendors": ["1", "2"],
    "collectedAt": 1686863416
}

The result will be a JSON object with users consent preferences for the jurisdiction specified in the request. This object has the same specification as the request with the addition of the protocols object if requested:

propertyvalue description
environmentCodecode for the environment in which the consent was collected
identitiesJSON object with the identity space code as property names and property corresponding to relevant the identity space.
jurisdictionCodejurisdiction code in which the consent was collected.
propertyCodeproperty code as defined within the Ketch Platform on which the consent was collected
purposesSame as request.
vendorsA list of vendor identifiers for which the user has opted out
protocolsA json object with the protocol identifier as the key and the protocol string corresponding to the consent as the value
{
    "environmentCode": "production",
    "identities": {
        "account_id": "120e710b-71c9-4134-a42g-f16541bff1c6"
    },
    "jurisdictionCode": "california_cpa",
    "propertyCode": "test",
    "purposes": {
        "PURPOSE_CODE_1": {
            "allowed": "false",
            "legalBasisCode": "consent_optout"
        },
        "PURPOSE_CODE_2": {
            "allowed": "false",
            "legalBasisCode": "consent_optout"
        },
        "PURPOSE_CODE_3": {
            "allowed": "false",
            "legalBasisCode": "consent_optout"
        },
        "PURPOSE_CODE_4": {
            "allowed": "true",
            "legalBasisCode": "consent_optout"
        }
    },
    "vendors": ["1", "2"],
    "protcols": {
        "tcf": "CPv736DPv736DFUABAENALEsAP_gAAAAACiQAAAAAAAA.YAAAAAAAAAA",
    }
}

Get subscription configuration

The Ketch subscriptions configuration contains all the information needed to create your custom subscriptions experience.

To get the configuration call the following API, replacing ORG_CODE and PROPERTY_CODE with their respective values.

GET https://global.ketchcdn.com/web/v2/config/ORG_CODE/PROPERTY_CODE/en/subscriptions.json

The result is a JSON object containing only the information needed to create the experience for the users current location. The location is determined by the users IP address when the call is made.

An example of the full configuration object can be found here.

The topics property on the resulting JSON object is needed to create the subscriptions experience.

Get subscriptions

POST https://global.ketchcdn.com/web/v2/subscriptions/ORG_CODE/get

propertyvalue description
organizationCode
propertyCodeproperty code as defined within the Ketch Platform on which the consent was collected
environmentCodecode for the environment in which the consent was collected
identitiesJSON object with the identity space code as property names and property corresponding to relevant the identity space.
{
  "organizationCode":"ORG_CODE",
  "propertyCode":"PROPERTY_CODE",
  "environmentCode":"ENVIRONMENT_CODE",
  "identities":{
    "SUBSCRIPTION_IDENTITY_1_CODE": "IDENTITY_1_VALUE",
    "SUBSCRIPTION_IDENTITY_2_CODE": "IDENTITY_2_VALUE",
    ...
  }
}

Set subscriptions

POST https://global.ketchcdn.com/web/v2/subscriptions/ORG_CODE/update

{
  "organizationCode":"ORG_CODE",
  "controllerCode":"",
  "propertyCode":"PROPERTY_CODE",
  "environmentCode":"ENVIRONMENT_CODE",
  "topics":{
    "TOPIC_1_CODE":{
      "email":{
        "status":"denied"
      },
      "sms":{
        "status":"denied"
      },
      "phone":{
        "status":"denied"
      },
      "mail":{
        "status":"denied"
      }
    },
    "TOPIC_2_CODE":{
      "email":{
        "status":"granted"
      },
      "sms":{
        "status":"granted"
      },
      "phone":{
        "status":"granted"
      },
      "mail":{
        "status":"granted"
      }
    },
    ...
  },
  "controls":{
    "global_control":{
      "status":"granted"
    }
  },
  "collectedAt":1691536512,
  "identities":{
    "SUBSCRIPTION_IDENTITY_1_CODE": "IDENTITY_1_VALUE",
    "SUBSCRIPTION_IDENTITY_2_CODE": "IDENTITY_2_VALUE",
    ...
  }
}

Determining when to show the Ketch Banner

To determine when you should show a banner/modal, you can use the following decision tree. It uses the information from the API calls to get configuration and consent.

From the configuration and gent consent calls, the decision tree uses properties from the purposes object on each of the returned objects.

Determining whether to show a banner or a modal

Once it's determined a consent experience needs to be shown, the next step is to determine what type of experience should be shown, banner or modal.

Use the following rules to help you determine which one to show:

  1. If any purpose has requiresOptIn set to true and experiences.consent.banner.secondaryButtonText is null in the configuration object, show a modal.
  2. Otherwise, use the default experience in the configuration object, experiences.consent.experienceDefault.
valuedescription
1Show a banner experience
2Show a modal experience

Note: if all purposes have requiresDisplay set to false, then show a banner experience regardless of the value.