Iubenda logo
Start generating

Documentation

Table of Contents

How to invoke Cookie Solution API methods from an iframe

If the Privacy Controls and Cookie Solution is embedded inside an iframe, all the _iub.cs.api methods can be called through postMessage. Here are some examples of how such calls can be made.

postMessage format

The API needs to receive a postMessage call in the following JSON format:

{ 
    __iubCsCall: { 
        command: <api-function-name>, 
        parameters: [...], 
        callId: <a-string-or-integer> 
   } 
}

Where:

  • command (string) is the name of the API function you want to call
  • parameters (array) is a list of parameters you’re sending to the API function
  • callId (string | int) is the Id used to verify that the returned output is for the same API call

Examples

Assuming that the target iframe is on https://example.com, we can send this API call:

ifr.postMessage(
    JSON.stringify({
        __iubCsCall: {
            command: 'isConsentGiven',
            parameters: [],
            callId: 1
        }
    }),
    'https://example.com'
);

This will call the Privacy Controls and Cookie Solution API function isConsentGiven() with no parameters. The output will be returned via postMessage as a JSON string.

In order for the message event to capture this output you’ll need a listener. Depending on the current Privacy Controls and Cookie Solution state, the listener will look like this:

{
    "__iubCsReturn": {
        "returnValue": false,
        "success": true,
        "callId": 1
    }
}

Example with parameters

Here’s how you can pass parameters to your postMessage call:

ifr.postMessage(
    JSON.stringify({
        __iubCsCall: {
            command: 'storeConsent',
            parameters: [{
                consent: false
            }],
            callId: 2
        }
    }),
    'http://localhost:3012'
);

This call to the storeConsent() function will set consent to false and store a consent cookie.

Refresh the page to see the effects of this call. After that, you can verify that the consent is set to false by evaluating _iub.cs.consent.consent in the console (it should output false).

The postMessage JSON output should look like this:

{
    "__iubCsReturn": {
        "success": true,
        "callId": 2
    }
}

Example of a malformed postMessage call

Here’s an output of a malformed postMessage call (e.g. an API function that doesn’t exist):

ifr.postMessage(
    JSON.stringify({
        __iubCsCall: {
            command: 'Consent',
            parameters: [{
                consent: false
            }],
            callId: 1
        }
    }),
    'http://localhost:3012'
);

Since there’s no API function called Consent in the Privacy Controls and Cookie Solution, as a result you should get an error like this:

{
    "__iubCsReturn": {
        "returnValue": null,
        "success": false,
        "callId": 1
    }
}

See also