Opt-in Reference

Last update: June 10, 2021

CREATED FOR:

Developer
User
Admin
Leader

API for the Opt-in library and configuration settings reference.

Consent settings are provided to the Opt-in functions as categories:

adobe.OptInCategories = {
    "AAM": "aam",
    "ANALYTICS": "aa",
    "ECID": "ecid",
    "TARGET": "target"
}

Opt-in Configuration parameters

This section discusses using the API to configure Opt-in. Much of the configuration and implementation can be done using the Experience Platform Launch extension.

Opt-in configurations are provided in the Visitor JavaScript getInstance() function, which instantiates the global adobe object. The following lists the Visitor JS configurations related to Opt-in service.

doesOptInApply (boolean or function that evaluates to a boolean):

If false, indicates visitors do not need to opt in. Results in Experience Cloud creating cookies regardless of categories opted in or out. This configuration holistically enables or disables Opt-in.

preOptInApprovals (Object <adobe.OptInCategories enum: boolean>)

Define which categories are approved or denied when no preference has yet been set by the visitor, referred to as organization defaults.

previousPermissions (Object<adobe.OptInCategories enum: boolean>)

The visitor’s explicitly set preferences. The permissions in this config overwrite organization defaults ( previousPermissions overwrites preOptInApprovals).

isOptInStorageEnabled (boolean)

Enable Opt-in to store the permissions in a first-party cookie (within the current customer’s domain)

(Optional) optInCookiesDomain (string)

First-party domain or sub-domain to use for the Opt-in cookie (if isOptInStorageEnabled is true)

(Optional) optInStorageExpiry (integer)

Number of seconds to override the default expiry of 13 months

Changes to Consent parameters

At any time during their experience on your site, a visitor may set preferences for the first time or may change their preferences using your CMP. Once Visitor JS has been initialized with initial settings, the visitor’s permissions can be changed using the following functions:

adobe.optIn.approve(categories, shouldWaitForComplete)

Function that approves, or opts the visitor in to all categories in a list. For more information on the shouldWaitForComplete parameter, see Opt-in Workflow.

adobe.optIn.deny(categories, shouldWaitForComplete)

Function that denies, or opts the visitor out of all categories specified.

adobe.optIn.approveAll():

If your request for permission for your site to create is phrased such that a visitor blanket grants or denies permission for your site to create cookies, use approveAll() or denyAll(), relative to their response.

adobe.optIn.denyAll():

If your request for permission for your site to create is phrased such that a visitor blanket grants or denies permission for your site to create cookies, use approveAll() or denyAll(), relative to the response.

Opt-in Workflows parameters

Opt-in supports a workflow where permissions can be collected over more than one request cycle, such as where preferences are given one at a time. Using the following functions and providing true for shouldWaitForComplete setting, your solution is able to collect consent for one solution or a subset of the total categories, then collect consent for the next one or subset of categories. Beginning on the first call, the adobe.optIn.status property will be pending until adobe.optIn.complete() is called at the end of the flow. Once called, the status is set to Complete.

adobe.optIn.approve(categories, shouldWaitForComplete)

Function that approves, or opts the visitor in to all categories in a list.

adobe.optIn.deny(categories, shouldWaitForComplete)

Function that denies, or opts the visitor out of all categories specified.

adobe.optIn.complete()

Function that triggers the aggregation of the proceeding calls to approve() and deny() into one request to set a visitor’s preferences. When subscribing to Opt-in changes (see adobe.optIn.fetchPermissions(callback, shouldAutoSubscribe) below, your callback is triggered only when this function is called.

Visitor Opt-in Permissions parameters

Collect Opt-in permissions for a visitor at any time using one of the permissions functions:

adobe.optIn.permissions

An object listing all Experience Cloud solutions, as categories, that have been granted or denied by the visitor.

adobe.optIn.isApproved(categories)

If all categories have been approved, this function will return true.

adobe.optIn.fetchPermissions(callback, shouldAutoSubscribe)

Retrieve the list of permissions asynchronously. The callback is called with the list of permissions, once the permissions granting / denying process is complete. Providing a value of true for shouldAutoSubscribe registers the callback for any Opt-in changes going forward. The following are properties of adobe.OptIn:

permissions

An object listing all Experience Cloud solutions, as categories, that have been granted or denied by the visitor Example: { aa: true, ecid: false, aam: true... }

status

pending
changed
complete

doesOptInApply

True or false, representing the configuration you provided in initialization

isPending

True or false, depending on status value. Opt-in reports true for this property for a visitor who has not yet explicitly accepted or denied permission

isComplete

True or false depending on status value. Opt-in might report a false for this property when a workflow-style consent has started but not completed.

Methods of Opt-in object

approve(categories, shouldWaitForComplete)

categories: One or more categories to approve. For example: adobe.optIn.approve([adobe.OptInCategories.AAM, adobe.OptInCategories.ECID])
shouldWaitForComplete: (optional) boolean parameter, false by default. If you pass true, Opt-in does not complete the approval process until you call adobe.optIn.complete(). This process is similar to a workflow.

<codeblock>
  adobe.optIn.approve(adobe.OptInCategories.ANALYTICS,
         true); adobe.optIn.approve(adobe.OptInCategories.ECID, true);
         adobe.optIn.complete()
</codeblock>

deny(categories, shouldWaitForComplete)

Pass 1 or more categories to check if they are approved.
If no categories passed in, ALL available categories are checked.

isApproved(categories)

Check if one or more categories is approved by the customer.

isPreApproved(categories)

Check if one or more categories were pre approved by the customer. (If they were passed in the preOptInApprovals config).

fetchPermissions(callback, shouldAutoSubscribe)

Async API to retrieve the list of permissions. The callback is called with the list of permissions, once the permissions granting / denying process is complete. shouldAutoSubscribe: A helper utility, will automatically subscribe this callback to all future events. Meaning the callback will get called every time an approval or denial trigger in Opt In. This way you are always updated, without subscribing to the events yourself.

Example

fetchPermissions

optIn.fetchPermissions(function (permissions) {
    // Here you can check if your category has been approved or not.
    // We recommend using `optIn.isApproved()` to check for permissions because it abstracts
       out the details of knowing exactly how the `permissions` list looks like.

    if (adobe.optIn.isApproved(MY_CATEGORY) {
        sendBeacon(); // Or something
    }
});

// OR: You can pass in `shouldAutoSubscribe` as true, your callback will be used to subscribe
to all OptIn events going forward:

function callback() {
    if (adobe.optIn.isApproved(MY_CATEGORY) {
        sendBeacon(); // Or something
    }
}

optIn.fetchPermissions(callback, true);

complete():

NOTE

Use only if you passed the shouldWaitForComplete parameter to approve or deny. This API completes the approval process. Example: adobe.optIn.complete().

approveAll():

Approves all existing Categories.

denyAll()

Deny all existing Categories.

Events of Opt-in object

complete:

Complete event triggers when the approval process has been completed. If you call approve/deny without passing shouldWaitForComplete, or approveAll/ denyAll, this event triggers. Or, if you pass shouldWaitForComplete, this event triggers when complete is called.

Example

<codeph>
  adobe.optIn.on("complete", callback);
</codeph>

recommendation-more-help