Configuring custom scenarios - API

This article provides further details on setting up a custom scenario using the API.

What is a custom scenario?

By default, Didomi ACM scans run three standard scenarios to help us gather sufficient data for generating a report.

There may be certain cases where our bot's default actions are not compatible with the way your CMP is configured. For example, our bot only searches for the "Refuse" button on the 1st layer of the consent notice. If it does not find this button, the scan is considered to have failed. In order to overcome situations like this (where the bot's expectations do not match the reality) a custom scenario can be configured using the API. 

Configuring a custom scenario

To configure a property via the API, please have the following information handy:

Obtaining the selector

In our example we are trying to get the bot to click on the "Disagree to all" button present on the second layer of the Didomi consent notice. The following steps show how to obtain the CSS selector for doing this: 

1. Step 1: navigate to the webpage you would like to scan (in our example, didomi.io).
   
2. Step 2: right click on the element you would like our bot to click on. Select "Inspect".
3. Right click on the element <button> and select "Copy" then "Copy selector".
4. Save this selector (in our case "#didomi-notice-learn-more-button" ) and continue with the steps to obtain the next element to click on. Click on "Configure" in the notice.
5. Right click on "Disagree to all" and select "Inspect".
6. Right click on the element <button> and select "Copy" then "Copy selector".
7. Save this selector (in our case "#didomi-consent-popup > div > div > div > div > div.didomi-consent-popup-footer.didomi-popup-footer > div > button.didomi-components-button.didomi-button.didomi-button-standard.standard-button"). You  can now proceed to customise the API call (steps below).

Creating the API request body

The typical API request has the following format:

{
    "name": "Custom action",
    "website": "https://www.didomi.io/",
    "scraper": {
        "schedule": "0 0 1 * *",
        "url": "https://www.didomi.io/",
        "pages": 10,
        "country": "fr",
        "enabled": true,
        "actions": [
            {
                "page": "first",
                "actions": [
                    {
                        "type": "clickOnElement",
                        "params": {
                            "selector": "#didomi-notice-learn-more-button"
                        }
                    },
                    {
                        "type": "clickOnElement",
                        "params": {
                            "selector": "#didomi-consent-popup > div > div > div > div > div.didomi-consent-popup-footer.didomi-popup-footer > div > button.didomi-components-button.didomi-button.didomi-button-standard.standard-button"
                        }
                    }
                ]
            }
        ],
        "scenarios":["NO_USER_CHOICE"]
    },
    "organization_id": "demo_org_id"
}

The elements in bold need to be present inside the JSON for the custom scenario to work. All the other elements should be filled in based on the information from the previous steps. 

Sending the request

Now that the request body has successfully been created, we need to send it to the POST /properties endpoint. Before doing this, we advise you to read the documentation presented here.