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.theme] optional: theme1 | theme2 | ... | theme16
  • [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: {theme: "theme12", 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.theme] optional: theme1 | theme2 | ... | theme16
  • [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
theme: theme5
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 (up to a maximum of 25 at once) 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.

Arguments

  • input: an array of configuration IDs
  • [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(
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": {
/* ... */
}
}
}
]
}