Iubenda logo

Documentation

Table of Contents

How to invoke Cookie Solution API methods from an iframe

If the 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 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 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 Cookie Solution, as a result you should get an error like this:

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

See also