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

Example:

import { UnifiedConsentByOsanoSDK } from '@unifiedconsentbyosano/cmp-javascript-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 ClientConfig parameter with an access token to be able to instantiate it. Returns a UnifiedConsentByOsanoClient instance.

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.

Signature:

UnifiedConsentByOsanoSDK.createClient(ClientConfig): UnifiedConsentByOsanoClient

Example:

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

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

registerPrivacyProtocols

Method to register the Privacy Protocols. This method is only available for the browser environment. Parameters: PrivacyProtocolsConfig

Signature:

UnifiedConsentByOsanoSDK.registerPrivacyProtocols(PrivacyProtocolsConfig): Promise<void>

Example:

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

await UnifiedConsentByOsanoSDK.registerPrivacyProtocols(
  {
    /** Osano's Unified Consent API URL */
    apiUrl: string,
    /** Write only api key*/
    apiKey: string,
    /** Gpc attributes*/
    attributes?: Record<string, any>
  }
)

initEmbeddedParent

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

Parameters: EmbeddedConfig

Signature:

UnifiedConsentByOsanoSDK.initEmbeddedParent(config: EmbeddedConfig): EmbeddedHandler

Example:

import { UnifiedConsentByOsanoSDK } from './UnifiedConsentByOsanoSDK'

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 createConsent(payload: CreateConsentPayload): 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[]

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