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.mergeAnonymousSubject
• UnifiedConsentByOsanoClient.saveProfile
• UnifiedConsentByOsanoClient.verifySubjectProfile
• UnifiedConsentByOsanoClient.getProfileVerificationCode
• UnifiedConsentByOsanoClient.mergeSubjects

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. This will return a UnifiedConsentByOsanoClient with the ability to submit consents, but not manage subjects. 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',
  token: accessToken,
  osanoApiKey: 'osano-api-key' // Optional. Should only be present on the server side.
})

registerPrivacyProtocols

Creates a GPC consent for the active subject. This method is only available for the browser environment.

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'

await UnifiedConsentByOsanoSDK.registerPrivacyProtocols(
  {
    /** Osano's Unified Consent API URL */
    apiUrl: string,
    /** Token generated by the getToken method */
    token: string,
    /** Gpc attributes */
    attributes?: Record<string, any>
    /** Cookie-related config*/
    cookieConfig?: CookieConfig
  }
)

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'),
})

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>

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: string - The status text of the response

async createGpcConsent(payload: CreateGpcConsentPayload): Promise<string>

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 In order to honor choices made as an anonymous user, mergeAnonymousSubject must be called on the server side BEFORE login is called in the browser.

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

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

mergeSubjects

Merges the consents of the source subject into the target subject.

Authorization: osanoApiKey
Parameters: sourceSubjectId: string - The subject to merge data from, targetSubjectId: string - The subject to merge data to
Response: void

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: osanoApiKey
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

::: tip The verified ID should not contain PII or sensitive information :::

Signature

static verified({
  id: string,
  profile?: {
    email: string,
    firstName?: string,
    lastName?: string
  }): Subject

Example

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

anonymous()

This will generate a subject with an auto-generated UUID

static anonymous(): Subject

Example

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	Payload
login	Triggered upon successful login	Subject
logout	Triggered upon successful logout	Subject
consent:write	Triggered when a consent is created	Action[]
consent:write:gpc	Triggered when a gpc consent is created	Action[]

on

Receives events from the child iframe and declares its behavior

Parameters: MessageType, MessageListener

Signature:

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

Example:

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

send

Sends events to the child iframe

Signature:

send(message: Message): void

Example:

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