API Reference

WireWheelSDK

getToken

Method that returns a token, which can then be used to instantiate a WireWheelClient. Meant to be called on a server side to protect the clientId and clientSecret values. Please see scopes for reference.

Example:

import { WireWheelSDK, Scopes } from '@wirewheelio/cmp-javascript-sdk'

const scopes = [Scopes.ConsentWrite]

const accessToken = await WireWheelSDK.getToken(
  {
    /** URL of authorization services provider */
    issuer: string,
    /** The client_id is the public identifier of your app */
    clientId: string,
    /** The client_secret is a secret known only to the application and the authorization server. */
    clientSecret: string,
  },
  scopes
)

createClient

The WireWheelClient 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 WireWheelClient instance.

Signature:

WireWheelSDK.createClient(ClientConfig): WireWheelClient

Example:

import { WireWheelSDK } from '@wirewheelio/cmp-javascript-sdk'

const client = WireWheelSDK.createClient({
  token: accessToken,
  apiUrl: 'https://api.demo.cmp.wirewheel.io',
})

registerPrivacyProtocols

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

Signature:

WireWheelSDK.registerPrivacyProtocols(PrivacyProtocolsConfig): Promise<void>

Example:

import { WireWheelSDK } from '@wirewheelio/cmp-javascript-sdk'

await WireWheelSDK.registerPrivacyProtocols(
  {
    /** WireWheel's UPCP 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:

WireWheelSDK.initEmbeddedParent(config: EmbeddedConfig): EmbeddedHandler

Example:

import { WireWheelSDK } from './WireWheelSDK'

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

WireWheelClient

createConsent

Parameters: CreateConsentPayload
Scopes: ConsentWrite

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

getChannelConfig

Retrieves the channel for a given channelId.

Parameters: channelId
Returns: Channel
Scopes: ConsentRead

async getChannelConfig(channelId: string): Promise<Channel>

getUnifiedConsent

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

getProfileVerificationCode

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

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

hasConsents

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

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. It calls mergeSubjects internally to honor choices made as an anonymous user. This only works in a browser environment.

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

loginFromSession

Given a valid Session ID generated via SSO login, this method will work exactly like login, resolving the verified ID and, if available, basic profile information. It calls mergeSubjects internally to honor choices made as an anonymous user. The return value of this method is a Session. This only works in a browser environment

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.

logout(): void

mergeSubjects

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

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

saveProfile

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

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

subject

Getter to access the Subject, if provided when instantiated

subject(): Subject

verifySubjectProfile

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

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