Custom actions via API

Premium Feature: Advanced Compliance Monitoring

Custom actions allow your organization to customize the behavior of the Didomi bot as it interacts with your consent notice and/or domain when scanning for a compliance report. In this article, we will cover how to leverage the Didomi API to configure custom actions in your organization's compliance report.

Resources

Before continuing with this article we recommend that your organization familiarizes itself with how to interact with the Didomi API. Refer to the resources below for more information:

• Introduction to Didomi API

• Didomi API specification

Use cases

There are two primary use cases to configure custom actions for the Didomi bot that scans your website:

Use case	Description
Custom scenario	Customize the Didomi bot behavior when navigating a consent notice that is not compatible with the default actions of the bot
Accessing a logged in environment	Customize the Didomi bot behavior when providing credentials is a multi-step process in the authentication process

Configure custom action API request

In this section, we will cover how to configure custom actions using the Didomi API for specific use cases and illustrate the process using an example.

Custom scenario

Alternatively, custom scenarios for the Didomi bot can be configured directly from the Didomi console. Click here to learn more.

By default, Advanced Compliance Monitoring scans for three standard scenarios (Accept all, Refuse all, and No actions) to gather sufficient data to generate the compliance report.

It can be the case that the Didomi bot used for scanning fails because the default behavior of the bot for the respective scenarios does not align with how your CMP is configured. In this tab, we will cover how to customize the bot behavior for a scenario via API.

• Example

• Retrieve CSS selector(s)

• API request

---

Example

In the example used in the API request below we are scanning a consent notice where the action to refuse all purposes and vendors is only present on the second layer of the consent notice. However, the default behavior of the Didomi bot is to only search for this action on the first layer of the consent notice and since it will not find this button to do, the scan for that scenario will fail.

The custom action via API will customize the Refuse all scenario behavior for the Didomi bot so that it navigates to the second layer of the consent notice where the button to refuse all purposes and vendors is present.

Retrieve CSS selector(s)

CSS selector values instruct the Didomi bot where to click (or insert text) to navigate through your consent notice. To collect the CSS selector values:

1. Navigate to your website and load your consent notice

2. Right-click the desired element on the consent notice where the Didomi bot should click (or insert text)

3. Select Inspect from the subsequent menu

The element should be highlighted in the Inspector. Right-click the highlighted item in the Inspector and select Copy > Copy selector (or CSS Selector depending on browser).

Repeat as necessary for elements that the Didomi bot will need to click in order to achieve the desired behavior.

For our custom Refuse all scenario, the Didomi bot will need to click the Learn More button on the first layer of the consent notice and then click the Disagree to all button on the second layer of the consent notice.

API request

In this section, we will cover how to construct the API request to customize the Refuse all scenario.

Didomi strongly encourages you to visit the API specification for creating a new property for the compliance report for all parameters available in the request. Additionally, ensure that your request also has the required bearer token in the Authorization header.

Endpoint

Your API request should be made to the following endpoint:

Method	POST
URL	https://api.didomi.io/v1/reports/compliances/properties
Query Parameter	organization_id

Body

When constructing the body of the API request, the custom scenario configuration is performed in scenarios[].scenario_actions for the respective scenario being customized. Add an object to scenarios[].scenario_actions for each step the Didomi bot should perform to execute the desired behavior.

For our custom Refuse all scenario, the Didomi bot should first click the Learn More button (identified by the CSS selector) and then the Disagree to all button (identified by the CSS selector). See line 20-35 in the example below.

{
  "name": "Custom Action API",
  "website": "https://demosite.com",
  "scenarios": [
    {
      "enabled": true,
      "type": "accept_all",
      "scenario_actions": [
        {
          "type": "accept",
          "order": 0
        }
      ]
    },
    {
      "enabled": true,
      "type": "no_actions",
      "scenario_actions": []
    },
    {
      "enabled": true,
      "type": "refuse_all",
      "scenario_actions": [
        {
          "type": "click",
          "order": 0,
          "css_selector": "#didomi-notice-learn-more-button"
        },
        {
          "type": "click",
          "order": 1,
          "css_selector": "#btn-toggle-disagree"
        }        
      ]
    }
  ],
  "enabled": true,
  "pages_count": 150,
  "country": "fr",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"
}

Accessing a logged in environment

1. Proceed the same when prompted for the password. Collect the imput selector for the password field.

2. Collect the css selector for the submit (continue) button.

Creating the API Request body

The typical API request has the following format:

{
    "name": "Custom action - login",
    "website": "https://console.didomi.io/",
    "scraper": {
        "schedule": "0 0 1 * *",
        "url": "https://console.didomi.io/",
        "pages": 10,
        "country": "fr",
        "enabled": true,
        "actions": [
            {
                "page": "first",
                "actions": [
                    {
                        "type": "type",
                        "params": {
                            "text":"<username>",
                            "selector": "#username"
                        }
                    },
                    {
                        "type": "clickOnElement",
                        "params": {
                            "selector": "#submit-button"
                        }
                    },
                    {
                        "type": "type",
                        "params": {
                            "text":"<password>",
                            "selector": "#Password"
                        }
                    },
                    {
                        "type": "clickOnElement",
                        "params": {
                            "selector": "#submit-button"
                        }
                    }
                ]
            }
        ],
        "scenarios":["NO_USER_CHOICE","CONSENT_TO_ALL","REFUSE_TO_ALL"]
    },
    "organization_id": "demo_org_id"
}

The elements in bold are all the steps required for the login to be performed. These actions will be done after the interaction of the bot with the notice. In case the notice is displayed after the login is performed we recommend you continue to add as custom scenario the interaction with the notice (see example 1).

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.

❗After adding a property using the API it might take a few hours for the scanning process to be triggered. If your report still has no data after 24 hours please contact your Didomi Account Manager.