Skip to main content

Modify Configurations

This API allows you to modify consent configurations that exist within your Osano Admin Application

See Consent Manager API - Setup for setup instructions.

Contents​

API​

In order to update a configuration, you must provide the configuration ID. To get this value, use the "Get Code" button to obtain your Osano.js.

Your osano.js will contain your Customer ID and your Configuration ID:

https://cmp.osano.com/CustomerID/ConfigurationID/osano.js

  • This API supports the following GraphQL mutations:
    • updateStyling: updates styling on an existing configuration
    • updateProperties: updates properties on an existing configuration
    • publish: publishes an existing configuration
    • addRules: adds classification rules to a configuration

Note: an optional webhook URL can be provided and will be called when the operation is complete.

updateStyling​

Updates the customizable (e.g. styling) options on an existing configuration. Changes must be published to take effect.

Arguments​

  • input
  • input.configId: the ID of the configuration to update
  • input.newStyling: the styling to modify (cannot be null or empty)
  • [input.newStyling.palette] optional: any palette modifications (see below)
  • [webhookURL] optional: A URL to be called when the operation is complete

Possible Palette Properties​

Colors must be given in CSS numerical format (hexadecimal, RGBa or HSLa). Color keywords are not supported.

{
    "palette": {
        "type": "object",
        "properties": {
            "displayPosition": {
                "type": "string",
                "enum": [
                    "top",
                    "right",
                    "bottom",
                    "left",
                    "topLeft",
                    "topRight",
                    "bottomLeft",
                    "bottomRight",
                    "center"
                ]
            },
            "dialogType": {
                "type": "string",
                "enum": ["bar", "box"]
            },
            "infoDialogPosition": {
                "type": "string",
                "enum": ["right", "left"]
            },
            "widgetPosition": {
                "type": "string",
                "enum": ["right", "left"]
            },
            "buttonBackgroundColor": {
                "type": "string"
            },
            "buttonForegroundColor": {
                "type": "string"
            },
            "buttonDenyBackgroundColor": {
                "type": "string"
            },
            "buttonDenyForegroundColor": {
                "type": "string"
            },
            "dialogBackgroundColor": {
                "type": "string"
            },
            "dialogForegroundColor": {
                "type": "string"
            },
            "infoDialogOverlayColor": {
                "type": "string"
            },
            "infoDialogBackgroundColor": {
                "type": "string"
            },
            "infoDialogForegroundColor": {
                "type": "string"
            },
            "linkColor": {
                "type": "string"
            },
            "toggleOffBackgroundColor": {
                "type": "string"
            },
            "toggleButtonOffColor": {
                "type": "string"
            },
            "toggleOnBackgroundColor": {
                "type": "string"
            },
            "toggleButtonOnColor": {
                "type": "string"
            },
            "widgetColor": {
                "type": "string"
            },
            "widgetOutlineColor": {
                "type": "string"
            },
            "widgetFillColor": {
                "type": "string"
            }
        },
        "additionalProperties": false
    }
}

Example Mutation Body​

mutation {
    updateStyling(
        input: {
            configId: "33331cd9-5823-41ac-8b47-3dadffb99ce0"
            newStyling: {palette: {linkColor: "#000"}}
        }
        # webhookURL is optional
        webhookURL: "https://example.com/webhook/updatecomplete"
    ) {
        ... on Config {
            configId
        }
    }
}

Example Success Response​

{
    "data": {
        "updateStyling": {
            "configId": "a651a88d-261e-456e-b620-d7ea5d38d300"
        }
    }
}

Example Error Response​

{
    "errors": [
        {
            "message": "Field \"nonexistentField\" is not defined by type \"Styling\".",
            "locations": [
                {
                    "line": 7,
                    "column": 13
                }
            ],
            "extensions": {
                "code": "GRAPHQL_VALIDATION_FAILED"
            }
        }
    ]
}

updateProperties​

Updates settings/properties on an existing configuration. Changes must be published to take effect.

Arguments​

  • input
  • input.configId: the ID of the configuration to update
  • input.newProperties: the properties to modify (cannot be null or empty)
  • [input.newProperties.name] optional: A new name
  • [input.newProperties.domains] optional: A list of domains to replace the current list (cannot be null or empty)
  • [input.newProperties.mode] optional: off | draft | debug | production | 'listener' | permissive | strict
  • [input.newProperties.orgNames] optional: A list of valid organization names ([] or null will clear this list)
  • [input.newProperties.configuration] optional
  • [input.newProperties.configuration.codeSplitting] optional: boolean
  • [input.newProperties.configuration.ccpaRelaxed] optional: boolean
  • [input.newProperties.configuration.crossDomain] optional: boolean
  • [input.newProperties.configuration.timeoutSeconds] optional: Number of seconds to wait before hiding the banner and saving default consent settings
  • [input.newProperties.configuration.storagePolicyHref] optional: The URL for your site's privacy policy (can be relative or absolute)
  • [webhookURL] optional: A URL to be called when the operation is complete

Example Mutation Bodies​

Update a bunch of properties at once:

mutation {
    updateProperties(
        input: {
            configId: "33331cd9-5823-41ac-8b47-3dadffb99ce0"
            newProperties: {
                name: "New Name For Your Config"
                domains: ["espresso.com", "latte.com"]
                mode: debug
                orgNames: ["USA", "LATM"]
                configuration: {
                    ccpaRelaxed: false
                    crossDomain: true
                    timeoutSeconds: 9
                    storagePolicyHref: "/coffee.html"
                }
            }
        }
        # webhookURL is optional
        webhookURL: "https://example.com/webhook/updatecomplete"
    ) {
        ... on Config {
            configId
        }
    }
}

Update 1 or 2 properties:

mutation {
    updateProperties(
        input: {
            configId: "33331cd9-5823-41ac-8b47-3dadffb99ce0"
            newProperties: {
                mode: permissive
                # null or [] will remove all orgs
                orgNames: null
                # ... the rest of the properties will be unchanged
            }
        }
        # webhookURL is optional
        webhookURL: "https://example.com/webhook/updatecomplete"
    ) {
        ... on Config {
            configId
        }
    }
}

Example Success Response​

{
    "data": {
        "updateProperties": {
            "configId": "a651a88d-261e-456e-b620-d7ea5d38d300"
        }
    }
}

Example Error Response​

{
    "errors": [
        {
            "message": "Invalid organization name(s): ZZZZ.",
            "locations": [
                {
                    "line": 2,
                    "column": 3
                }
            ],
            "path": ["updateProperties"],
            "extensions": {
                "code": "DATABASE_ERROR"
            }
        }
    ],
    "data": null
}

publish​

Publishes existing configurations and returns a list of the IDs for all configurations that were successfully added to the publish queue as well as the number of configurations, if any, that failed to add to the publish queue.

Limits & Guidelines​

  • Maximum 250 configs per request
  • Maximum 300 configs per account queued for publish at one time
  • Configs queued for publish cannot be queued again until publish is complete

Do NOT publish after each change. Instead, make all changes, then publish each changed config only once, with as few requests as possible. There is no benefit to multiple publishes, but it backs up the pubish queue.

Publish 250 at once, wait 30 minutes before publishing 250 more, and so on. - Important: This is NOT equivalent to publishing 8 per minute or any other spreading of the 250 over the 30 minutes. Publishing autoscales based on how many are queued. Without enough queued publishes, autoscaling isn't triggered and publishes are processed more slowly.

Arguments​

  • input: an array of configuration IDs (250 maximum)
  • [webhookURL] optional: A URL to be called when the operation is complete

Example Mutation Body​

mutation {
    publish(
        input: [
            "2aaa1f8e-a02e-4e07-9ced-7723e3e54c89"
            "2ee5ede3-370d-4df1-b670-a82d1a091890"
        ]
        # webhookURL is optional
        webhookURL: "https://example.com/webhook/updatecomplete"
    ) {
        ... on Configs {
            configIds
            errorCount
        }
    }
}

Example Success Response​

{
    "data": {
        "publish": {
            "configIds": [
                "2ebb1f8e-a02e-4e07-9ced-7723e3e54c70",
                "4ff5ede3-370d-4df1-b670-a82d1a09189d"
            ],
            "errorCount": 0
        }
    }
}

Example Partial Success Response​

{
    "data": {
        "publish": {
            "configIds": [
                "2ebb1f8e-a02e-4e07-9ced-7723e3e54c70"
            ],
            # There were 2 IDs in the input. One failed and the ID of the success is above.
            "errorCount": 1
        }
    }
}

Example Error Response​

{
    "errors": [
        {
            "message": "Invalid: `input` must contain at least 1 config ID",
            "locations": [
                {
                    "line": 2,
                    "column": 3
                }
            ],
            "path": ["publish"],
            "extensions": {
                "argumentName": "input",
                "code": "BAD_USER_INPUT"
            }
        }
    ],
    "data": null
}

addRules​

Adds classification rules to existing configurations (up to a maximum of 25 at once) and returns a list of the IDs for all configurations that were successfully updated.

Arguments​

  • input
  • input.configIds: an array of configuration IDs (up to a maximum of 25 at once)
  • input.cookies, input.iframes, input.scripts: arrays of rules to be added. Each rule is an object with the following properties:
    • classification string
    • rule string: minimum 3 and maximum 1000 characters
    • description optional: string, maximum 1000 characters
    • disclosure optional: boolean, whether this rule requires disclosure
    • expiry optional: string, maximum 50 characters
    • vendorName optional: string, maximum 100 characters

Example Mutation Body​

mutation {
    addRules(
        input: {
            configIds: [
                "2aaa1f8e-a02e-4e07-9ced-7723e3e54c89",
                "2ee5ede3-370d-4df1-b670-a82d1a091890"
            ]
            cookies: [
                {
                    classification: ESSENTIAL,
                    rule: "^__cfruid$"
                },
                {
                    classification: ANALYTICS,
                    description: "A cookie disclosure descpription",
                    disclosure: true,
                    expiry: "1 year",
                    rule: "__utma",
                    vendorName: "Google Analytics"
                }
            ],
            iframes: [
                {
                    classification: MARKETING,
                    rule: "https://www.youtube.com/embed"
                },
                {
                    classification: ESSENTIAL,
                    rule: "https://surveyhero.com/e/"
                }
            ]
            scripts: [
                {
                    classification: ANALYTICS,
                    rule: "hs-analytics\.net"
                },
                {classification: ESSENTIAL, rule: "googletagmanager\.com"}
            ]
        }
    ) {
        ... on Configs {
            configIds
            errorCount
        }
    }
}

Example Success Response​

{
    "data": {
        "addRules": {
            "configIds": [
                "2aaa1f8e-a02e-4e07-9ced-7723e3e54c89",
                "2ee5ede3-370d-4df1-b670-a82d1a091890"
            ],
            "errorCount": 0
        }
    }
}

Example Partial Success Response​

{
    "data": {
        "addRules": {
            "configIds": [
                "2aaa1f8e-a02e-4e07-9ced-7723e3e54c89"
            ],
            # There were 2 IDs in the input. One failed and the ID of the success is above.
            "errorCount": 1
        }
    }
}

Example Error Response​

{
    "errors": [
        {
            "message": "Field \"AddRulesInput.configIds\" of required type \"[String!]!\" was not provided.",
            "locations": [
                {
                    "line": 3,
                    "column": 12
                }
            ],
            "extensions": {
                "code": "GRAPHQL_VALIDATION_FAILED",
                "exception": {
                    /* ... */
                }
            }
        }
    ]
}