API Reference

UnifiedConsentByOsanoSDK

getToken

Method that returns a token, which is required to instantiate a UnifiedConsentByOsanoClient. The issuer, configId, customerId, and the returned token are not sensitive. The token can be generated by, or passed along to the client application.

This token will give you access to all UnifiedConsentByOsanoClient methods EXCEPT the following (see createClient for more information on enabling these methods):

• UnifiedConsentByOsanoClient.saveProfile
• UnifiedConsentByOsanoClient.getProfileVerificationCode

The issuer, configId, and customerId can be provided in one of two ways:

1. By setting the window.UcByOsanoSdkConfig object - Find out more on the Configuration page
2. By explicitly passing the issuer, configId, and customerId to getToken

When issuer, configId, and customerId are provided to the getToken function, window.UcByOsanoSdkConfig will be ignored completely

Example:

import { UnifiedConsentByOsanoSDK } from '@osano/unified-consent-js-sdk'

const accessToken = await UnifiedConsentByOsanoSDK.getToken(
  {
    /** URL of authorization services provider */
  issuer: string,
  /** The  config Id */
  configId: string,
  /** The Client Id */
  customerId: string
  }
)

createClient

The UnifiedConsentByOsanoClient can be used from a browser or node environment. It requires the configuration to contain an access token and an API url to be able to instantiate it. Returns a UnifiedConsentByOsanoClient instance.

A ClientConfig can be provided in one of two ways:

1. By setting the window.UcByOsanoSdkConfig object - Find out more on the Configuration page
2. By explicitly passing the ClientConfig as a param to createClient

When a ClientConfig is provided to the createClient function, window.UcByOsanoSdkConfig will be ignored completely

At a minimum the token and apiUrl must be provided. apiUrl is https://uc.api.osano.com/v2; the SDK does not add /v2 for you. This returns a UnifiedConsentByOsanoClient that can submit consents and use the token-authorized subject methods, but cannot call saveProfile or getProfileVerificationCode without an osanoApiKey. This is suitable for use in a browser environment.

Additionally, the osanoApiKey can be optionally provided to return a UnifiedConsentByOsanoClient with the capability to manage subject profiles. The osanoApiKey value is sensitive, and MUST NOT be exposed to the client application. For this reason, the osanoApiKey should only be present in the ClientConfig when creating a UnifiedConsentByOsanoClient on the server side.

Parameters: ClientConfig

Signature:

UnifiedConsentByOsanoSDK.createClient(clientConfig?: ClientConfig): UnifiedConsentByOsanoClient

Example:

import { UnifiedConsentByOsanoSDK } from 'unifiedconsentbyosano/cmp-javascript-sdk'

const client = UnifiedConsentByOsanoSDK.createClient({
  apiUrl: 'https://uc.api.osano.com/v2',
  token: accessToken,
  osanoApiKey: 'osano-api-key' // Optional. Should only be present on the server side.
})

registerPrivacyProtocols

Records a GPC (Global Privacy Control) consent for the visitor and sends it to the tag managers. It only works in the browser and throws anywhere else.

What it does:

1. Gets the subject from the SDK cookie, creating an anonymous one if there is none.
2. If the cookie already holds GPC actions, it fetches the published collection (GET /v2/collections). If the stored actions still match the collection's GPC defaults, it stops there.
3. Otherwise it calls POST /v2/consents/gpc and stores the returned gpcActions in the cookie. It then pushes the visitor's combined consent state to Google Tag Manager and Tealium: the GPC actions, the visitor's stored choices for privacy protocols GPC does not cover, and cookieConfig.defaultActions for protocols neither covers.

When to call it: on page load, for visitors whose browser sends the GPC signal. The SDK does not check navigator.globalPrivacyControl itself, so check it before calling. Because of step 2, calling it on every page load is safe.

A PrivacyProtocolsConfig can be provided in one of two ways:

1. By setting the window.UcByOsanoSdkConfig object - Find out more on the Configuration page
2. By explicitly passing the PrivacyProtocolsConfig as a param to registerPrivacyProtocols

When a PrivacyProtocolsConfig is provided to the registerPrivacyProtocols function, window.UcByOsanoSdkConfig will be ignored completely

Parameters: PrivacyProtocolsConfig

Signature:

UnifiedConsentByOsanoSDK.registerPrivacyProtocols(privacyProtocolsConfig?: PrivacyProtocolsConfig): Promise<void>

Example:

import { UnifiedConsentByOsanoSDK } from '@osano/unified-consent-js-sdk'

if (navigator.globalPrivacyControl) {
  await UnifiedConsentByOsanoSDK.registerPrivacyProtocols({
    apiUrl: 'https://uc.api.osano.com/v2',
    /** Token generated by getToken */
    token: accessToken,
    /** Optional */
    attributes: { platform: 'Linux x86_64' },
  })
}

getConsentDecisionType

Retrieves the current consent decision type for the active subject.

A CookieConfig can be provided in one of two ways:

1. By setting the window.UcByOsanoSdkConfig object - Find out more on the Configuration page
2. By explicitly passing the CookieConfig as a param to getConsentDecisionType

When a CookieConfig is provided to getConsentDecisionType, window.UcByOsanoSdkConfig will be ignored completely

Parameters: CookieConfig

Response: ConsentType: The type of the current consent, explicit or implicit. ConsentType

Signature:

static getConsentDecisionType(config?: CookieConfig): ConsentType

Example:

import { UnifiedConsentByOsanoSDK } from '@osano/unified-consent-js-sdk'

const currentConsentDecisions = UnifiedConsentByOsanoSDK.getCurrentConsentDecision({
  expirationInDays: 30
})

getCurrentConsentDecision

Retrieves the current consent decisions for the active subject.

A CookieConfig can be provided in one of two ways:

1. By setting the window.UcByOsanoSdkConfig object - Find out more on the Configuration page
2. By explicitly passing the CookieConfig as a param to getCurrentConsentDecision

When a CookieConfig is provided to getCurrentConsentDecision, window.UcByOsanoSdkConfig will be ignored completely

Parameters: CookieConfig

Response: Array<Action>: An array of unique actions representing the current consent decisions. Action

Signature:

static getCurrentConsentDecision(config?: CookieConfig): Array<Action>

Example:

import { UnifiedConsentByOsanoSDK } from '@osano/unified-consent-js-sdk'

const currentConsentDecisions = UnifiedConsentByOsanoSDK.getCurrentConsentDecision({
  expirationInDays: 30
})

initEmbeddedParent

Creates an EmbeddedHandler instance and initializes the SDK for the embedded experience. This method is only available for the browser environment.

An EmbeddedConfig can be provided in one of two ways:

1. By setting the window.UcByOsanoSdkConfig object - Find out more on the Configuration page
2. By explicitly passing the EmbeddedConfig as a param to initEmbeddedParent

When an EmbeddedConfig is provided to the initEmbeddedParent function, window.UcByOsanoSdkConfig will be ignored completely

Parameters: EmbeddedConfig

Signature:

UnifiedConsentByOsanoSDK.initEmbeddedParent(config: EmbeddedConfig): EmbeddedHandler

Example:

import { UnifiedConsentByOsanoSDK } from '@osano/unified-consent-js-sdk'

const embeddedClient = UnifiedConsentByOsanoSDK.initEmbeddedParent({
  targetIframe: document.getElementById('iframeId'),
})

initEmbeddedChild

Creates an EmbeddedHandler for the page loaded inside the iframe and answers the parent's handshake. The hosted Consumer UI already calls it, so you only need it if you build your own page for the iframe.

It returns undefined when the page is not inside an iframe.

Parameters: ChildEmbeddedConfig

Signature:

UnifiedConsentByOsanoSDK.initEmbeddedChild(config?: ChildEmbeddedConfig): EmbeddedHandler | undefined

Example:

import { UnifiedConsentByOsanoSDK } from '@osano/unified-consent-js-sdk'

// In the page loaded in the iframe
const embeddedHandler = UnifiedConsentByOsanoSDK.initEmbeddedChild()

UnifiedConsentByOsanoClient

createConsent

Creates a consent for a subject, using the CreateConsentPayload

Authorization: token
Parameters: CreateConsentPayload Response: string - The status text of the response

async createConsent(payload: CreateConsentPayload): Promise<string>

Example:

import { ActionType } from '@osano/unified-consent-js-sdk'

await client.createConsent({
  actions: [{ target: 'privacy-protocol-id', vendor: 'config-id', action: ActionType.Accept }],
  attributes: { platform: 'Linux x86_64' },
})

createGpcConsent

Creates a GPC consent for a subject, using the CreateGpcConsentPayload. No actions need to be passed, as the GPC consent configuration is resolved in the Core API.

Authorization: token
Parameters: CreateGpcConsentPayload
Response: Action[] - the gpcActions returned by POST /v2/consents/gpc.

async createGpcConsent(payload: CreateGpcConsentPayload): Promise<Action[]>

Example:

const gpcActions = await client.createGpcConsent({
  subject: client.subject,
  compliance: { gpc: 1 },
  attributes: {},
})

// Consent state after GPC was applied
const { unifiedConsent } = await client.getUnifiedConsent()

getUnifiedConsent

Retrieves a unified consent for a subject. If a subject ID is passed, then that subject's unified consent will be returned. Otherwise, it will return the unified consent for the currently active subject.

Authorization: token
Parameters: subjectId?: string - Optional. The subject ID to retrieve a unified consent for. If none is passed, the active subjectId will be used.
Response: GetUnifiedConsentResponse

async getUnifiedConsent(subjectId?: string): Promise<GetUnifiedConsentResponse>

getProfileVerificationCode

Generates and returns a 6-digit profile verification code for a profile by email

Authorization: osanoApiKey
Parameters: email: string - The email to generate a profile verification code for
Response: string - The 6-digit profile verification code

async getProfileVerificationCode(email: string): Promise<string>

hasConsents

Returns true or false if at least one consent exists for the given subject

Authorization: token
Parameters: HasConsentsPayload
Response: boolean

async hasConsents({ subjectId?: string }): Promise<boolean>

login

Stores the given verified ID and uses it in future subject-aware endpoints like createConsent, getUnifiedConsent, etc to avoid having to pass the subject. This only works in a browser environment.

Authorization: none
Parameters: verifiedId: string - the verifiedId of the subject to login
Response: void

IMPORTANT login does not merge the anonymous subject. To keep choices made before login, call mergeSubjects first, with the anonymous ID as the source and the verified ID as the target. In the browser, mergeAnonymousSubject does the same using the anonymous ID stored by the SDK. loginFromSession merges for you.

const anonymousId = client.subject?.anonymousId

if (anonymousId) {
  await client.mergeSubjects(anonymousId, 'some-internal-id')
}
await client.login('some-internal-id')

async login(verifiedId: string): Promise<void>

loginFromSession

Given a valid Session ID generated via SSO login, this method resolves the verified ID and, if available, basic profile information, then stores the verified subject like login. The return value of this method is a Session. This only works in a browser environment.

IMPORTANT Unlike login, loginFromSession merges the anonymous subject into the verified one for you, so choices made before login are kept.

Authorization: token
Parameters: sessionId: string - a valid Session ID generated via SSO login
Response: Session

async loginFromSession(sessionId: string): Promise<Session>

logout

Removes the associated verified ID and generates an anonymous ID instead to be used in subject-aware endpoints when a subject is not explicitly provided. This only works in a browser environment.

Authorization: none

logout(): void

mergeAnonymousSubject

A browser shortcut for mergeSubjects. It reads the anonymous ID stored by the SDK and calls mergeSubjects(anonymousId, verifiedId). It does nothing when there is no anonymous subject. On a server, call mergeSubjects instead.

Authorization: token
Parameters: verifiedId: string - The verified ID to merge the anonymous subject into
Response: void

async mergeAnonymousSubject(verifiedId: string): Promise<void>

mergeSubjects

Merges the consents of the source subject into the target subject (POST /v2/subjects/merge). When a visitor logs in, the anonymous ID is the source and the verified ID is the target.

Authorization: token
Parameters: sourceSubjectId: string - The subject to merge data from (the anonymous ID), targetSubjectId: string - The subject to merge data to (the verified ID)
Response: void

await client.mergeSubjects(anonymousId, verifiedId)

async mergeSubjects(sourceSubjectId: string, targetSubjectId: string): Promise<void>

saveProfile

Creates or updates a user profile in the system and returns their verified ID

Authorization: osanoApiKey
Parameters: SaveProfilePayload
Response: string - The verified ID of the saved profile

async saveProfile({ email: string, profile: any }): Promise<string>

subject

Getter to access the Subject, if provided when instantiated

Response: Subject

subject(): Subject

verifySubjectProfile

Recieves a verification code generated with getProfileVerificationCode. Returns the verified id of the subject

Authorization: token
Parameters: VerifySubjectProfilePayload
Response: string - The verified ID of the saved profile

async verifySubjectProfile({ email: string, verificationCode: string }): Promise<string>

Subject

A subject represents the person that's giving consent.

A Subject might have two different ids. When they are not identified in the system, this SDK will generate a random UUID to identify the current device. Once the Subject is logged into the system, it can be converted to a verified Subject. A verified Subject has a custom id arbitrarily provided by you.

verified()

Creates a Subject with a verified ID from the third party system. The id becomes the subject's verifiedId.

tip

The verified ID should not contain PII or sensitive information

Signature

static verified(id: string): Subject

Example

import { Subject } from '@osano/unified-consent-js-sdk'

const subject = Subject.verified('some-internal-id')

anonymous()

This will generate a subject whose anonymousId is the given ID, or an auto-generated UUID if none is passed

static anonymous(id?: string): Subject

Example

import { Subject } from '@osano/unified-consent-js-sdk'

const subject = Subject.anonymous()

EmbeddedHandler

Handler to send and receive events from a parent window to a child iframe. This client is only available for the browser environment

Types of messages

Messages are specific events that exist only in the browser environment and are triggered when some specific actions are issued in the context of an embedded experience.

Message type	Description	data
login	Triggered upon successful login	{ subject: Subject }
logout	Triggered upon successful logout	{ subject: Subject }
consent:write	Triggered when a consent is created	{ actions: Action[] }
consent:write:gpc	Triggered when a gpc consent is created	{ actions: Action[] }
child:init	Sent by the parent every 250 ms until the child answers (handshake)	{ subject?: Subject, parentDomain: string, sessionId?: string }
child:loaded	Sent by the child in reply to child:init (handshake)	{ subject?: Subject }

Import MessageType from the package, or use window.unifiedConsentJsSdk.MessageType in the browser.

on

Receives events from the child iframe and declares its behavior

Parameters: MessageType, MessageListener

Signature:

on(type: MessageType, listener: MessageListener): void

Example:

import { MessageType } from '@osano/unified-consent-js-sdk'

embeddedClient.on(MessageType.LOGIN, (message) => {
  const { subject } = message.data
})

send

Sends events to the child iframe

Signature:

send(message: Message): void

Example:

import { MessageType } from '@osano/unified-consent-js-sdk'

embeddedClient.send({ type: MessageType.LOGIN, data: { subject } })

getParentDomain

Gets the domain from the parent window once the handshake between parent and child is completed. Until then, it returns undefined.

Signature:

getParentDomain(): string | undefined