Configuring custom actions - API

This article provides further details on setting up a custom action 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 action can be configured using the API. 

Another situation where a custom action comes in handy could be a specific logging in system. Both examples are covered below.

Configuring a custom action

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

{ 
 "type": "type",
 "params":
 { 
    "text":"<text to insert>",
     "selector": "#css_selector" 
 } 
}

{
 "type": "clickOnElement",
 "params": 
 {
   "selector": "#css_selector" 
 } 
}

{ 
 "type": "eval", 
 "params":
 {
  "script":"<js script to run>" 
 }
}

{
"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" 
 } 
}

Example 1: Changing interaction with the notice

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.

Example 2: Performing a custom logged in scenario

Obtaining the css selector

In this example we will try to perform a log in on a website where the implementation is in 2 steps, first you fill the username and submit and then the password and submit again.

1. Step 1: navigate to the webpage you would like to scan and login (in our example, console.didomi.io).
   
   
   
2. Step 2: right click on the element you would like our bot to insert the text. Select "Inspect".
   
3. Right click on the element <input> and select "Copy" then "Copy selector".
   
4. Step 4: right click on the element you would like our bot to click on (submit button). Select "Inspect".
   
5. Right click on the element <button> and select "Copy" then "Copy selector".
   
6. Proceed the same when prompted for the password. Collect the imput selector for the password field.
   
   
7. Collect the css selector for the submit (continue) button. 
   
   
8. Now that we have all the selectors we can proceed with creating the API Request body. 

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.