IOTT

Constructors

Constructor

new IOTT(options): IOTT

Initialize the SDK

Parameters

options

InitOptions

Initialization options

Returns

IOTT

Instance of the SDK

Example

const sdk = new IOTT({
  apiKey: 'your-api-key',
});

Analytics

trackEvent()

trackEvent(eventName, payload?): Promise<void>

Track an analytics event

Parameters

eventName

string

Name of the event to track

payload?

Record<string, unknown>

Additional data to associate with the event

Returns

Promise<void>

Gifting

createGiftingMessage()

createGiftingMessage(experienceId, itemSlug, message, files?): Promise<void>

Create a gifting message

Parameters

experienceId

string

ID of the gifting experience

itemSlug

string

ID of the item to create message for

message

GiftingMessage

The gifting message to create

files?

(Blob | File | Buffer<ArrayBufferLike>)[]

Returns

Promise<void>

Example

await sdk.createGiftingMessage('experience-id', 'item-id', {
  to: 'Peter',
  from: 'Alex',
  occasion: 'just_because',
  text: 'Hey Peter, just wanted to say you\'re awesome! 😊'
});

// With file attachment
const audioFile = new File([audioBlob], 'message.mp3', { type: 'audio/mp3' });
await sdk.createGiftingMessage('experience-id', 'item-id', {
  to: 'Peter',
  from: 'Alex',
  occasion: 'birthday',
  text: 'Happy Birthday Peter!'
}, [audioFile]);

deleteGiftingMessage()

deleteGiftingMessage(experienceId, itemSlug): Promise<void>

Delete a gifting message

Parameters

experienceId

string

ID of the gifting experience

itemSlug

string

ID of the item to delete message for

Returns

Promise<void>

Example

await sdk.deleteGiftingMessage('experience-id', 'item-id');

getGiftingMessage()

getGiftingMessage(experienceId, itemSlug): Promise<GiftingMessage>

Get a gifting message

Parameters

experienceId

string

ID of the gifting experience

itemSlug

string

ID of the item to get message for

Returns

Promise<GiftingMessage>

The gifting message

Example

const message = await sdk.getGiftingMessage('experience-id', 'item-id');
console.log(message.text);

getGiftingMessageStatus()

getGiftingMessageStatus(experienceId, itemSlug): Promise<GiftingMessageStatus>

Get the status of a gifting message

Parameters

experienceId

string

ID of the gifting experience

itemSlug

string

ID of the item to check status for

Returns

Promise<GiftingMessageStatus>

Status of the gifting message

Example

const status = await sdk.getGiftingMessageStatus('experience-id', 'item-id');
console.log(status.valid);

getGiftingStatus()

getGiftingStatus(experienceId): Promise<GiftingExperienceStatus>

Get the status of a gifting experience

Parameters

experienceId

string

ID of the gifting experience

Returns

Promise<GiftingExperienceStatus>

Status of the gifting experience

Example

const status = await sdk.getGiftingStatus('experience-id');
console.log(status.isActive);

signupForGifting()

signupForGifting(experienceId, entry): Promise<void>

Sign up for a gifting experience

Parameters

experienceId

string

ID of the gifting experience

entry

GiftingMessageSubmission

Gifting message submission details

Returns

Promise<void>

Example

await sdk.signupForGifting('experience-id', {
  itemSlug: 'item-slug',
  email: 'user@example.com',
  firstName: 'John',
  lastName: 'Doe'
});

Golden Ticket

checkGoldenTicketEntry()

checkGoldenTicketEntry(id, uid): Promise<GoldenTicketEntryStatus>

Check if a participant has already entered the golden ticket experience

Parameters

id

string

ID of the golden ticket to check entry for

uid

string

User ID to check the entry status for

Returns

Promise<GoldenTicketEntryStatus>

Golden ticket entry status for the given ID and user ID

Example

const status = await sdk.checkGoldenTicketEntry('golden-ticket-id', 'user-id');
console.log(status.hasEntered);

claimGoldenTicketCode()

claimGoldenTicketCode(id, uid, code): Promise<GoldenTicketWinStatus>

Claim a golden ticket code

Parameters

id

string

ID of the golden ticket

uid

string

User ID claiming the code

code

string

The golden ticket code to claim

Returns

Promise<GoldenTicketWinStatus>

Example

await sdk.claimGoldenTicketCode('golden-ticket-id', 'user-id', 'ABC123');

getGoldenTicketStatus()

getGoldenTicketStatus(id): Promise<GoldenTicketStatus>

Retrieve the golden ticket status for a given ID

Parameters

id

string

ID of the golden ticket to retrieve the status for

Returns

Promise<GoldenTicketStatus>

Golden ticket status for the given ID

Example

const status = await sdk.getGoldenTicketStatus('golden-ticket-id');
console.log(status.isActive);

signupForGoldenTicket()

signupForGoldenTicket(id, entry, images?): Promise<void>

Sign up for a golden ticket experience

Parameters

id

string

ID of the golden ticket to signup for

entry

Omit<GoldenTicketEntry, "images">

Golden ticket entry details

images?

(Blob | File | Buffer<ArrayBufferLike>)[]

Array of jpeg format images to upload

Returns

Promise<void>

Example

await sdk.signupForGoldenTicket('golden-ticket-id', {
 uid: 'user-id',
 email: 'user@email.com',
 firstName: 'John',
 lastName: 'Doe',
 code: 'ABC123',
 extra: {
   favoriteColor: 'blue',
 }
});

ID Meta Data

getMeta()

getMeta(id): Promise<null | Record<string, unknown>>

Retrieve the meta data for a given ID

Parameters

id

string

ID of the meta data to retrieve

Returns

Promise<null | Record<string, unknown>>

Meta data for the given ID

setMeta()

setMeta(id, payload): Promise<null | Record<string, unknown>>

Set the meta data for a given ID

Parameters

id

string

ID of the meta data to set

payload

Record<string, unknown>

Meta data to set

Returns

Promise<null | Record<string, unknown>>

Updated meta data for the given ID

Loyalty

claimLoyaltyItem()

claimLoyaltyItem<LoyaltyHistory>(experienceId, itemSlug, email): Promise<LoyaltyHistory>

Claim a loyalty item for a user

Type Parameters

LoyaltyHistory

LoyaltyHistory

Parameters

experienceId

string

ID of the loyalty experience

itemSlug

string

Item slug of the loyalty item to claim

email

string

Email of the user claiming the item

Returns

Promise<LoyaltyHistory>

Updated loyalty history with stamps

Example

const history = await sdk.claimLoyaltyItem('experience-id', 'item-id', 'user@example.com');
console.log(history.stamps.length);

getItemClaimStatus()

getItemClaimStatus(experienceId, itemId): Promise<ItemClaimStatus>

Get the claim status of a loyalty item

Parameters

experienceId

string

ID of the loyalty experience

itemId

string

ID of the loyalty item to check

Returns

Promise<ItemClaimStatus>

Claim status of the loyalty item

Example

const status = await sdk.getItemClaimStatus('experience-id', 'item-id');
console.log(status.claimed);

getStampHistory()

getStampHistory(experienceId, email): Promise<LoyaltyHistory>

Get stamp history for a user

Parameters

experienceId

string

ID of the loyalty experience

email

string

Email of the user

Returns

Promise<LoyaltyHistory>

Loyalty history with stamps

Example

const history = await sdk.getStampHistory('experience-id', 'user@example.com');
console.log(history.stamps.length);

registerLoyaltyUser()

registerLoyaltyUser(experienceId, entry, images?): Promise<LoyaltyHistory>

Register a new user for the loyalty program

Parameters

experienceId

string

ID of the loyalty experience

entry

Omit<LoyaltySignup, "images">

Loyalty signup data containing itemSlug, email, and optional user details

images?

(Blob | File | Buffer<ArrayBufferLike>)[]

Optional array of images to upload with the registration

Returns

Promise<LoyaltyHistory>

Loyalty history with initial stamp

Example

const history = await sdk.registerLoyaltyUser('experience-id', {
  itemSlug: 'item-123',
  email: 'user@example.com',
  firstName: 'John',
  lastName: 'Doe'
});
console.log(history.stamps.length);

Raffle

checkCompetitionEntry()

checkCompetitionEntry(id, uid, itemSlug?): Promise<CompetitionEntryStatus>

Retrieve the competition entry status for a given ID and user ID

Parameters

id

string

ID of the competition to retrieve the entry status for

uid

string

User ID to check the entry status for

itemSlug?

string

Returns

Promise<CompetitionEntryStatus>

Competition entry status for the given ID and user ID

Example

const status = await sdk.checkCompetitionEntry('competition-id', 'user@email.com');
console.log(status.hasEntered);

getCompetitionStatus()

getCompetitionStatus(id): Promise<CompetitionStatus>

Retrieve the competition status for a given ID

Parameters

id

string

ID of the competition to retrieve the status for

Returns

Promise<CompetitionStatus>

Competition status for the given ID

Example

const status = await sdk.getCompetitionStatus('competition-id');
console.log(status);

signupForCompetition()

signupForCompetition(id, entry, images?): Promise<void>

Signup for a competition

Parameters

id

string

ID of the competition to signup for

entry

Omit<CompetitionEntry, "images">

Competition entry details

images?

(Blob | File | Buffer<ArrayBufferLike>)[]

Array of jpeg format images to upload

Returns

Promise<void>

Example

await sdk.signupForCompetition('competition-id', {
 uid: 'user@email.com',
 email: 'user@email.com'
 firstName: 'John',
 lastName: 'Doe',
 extra: {
  favoriteColor: 'blue',
 }
});

Scan & Register

checkBasicExperienceEntry()

checkBasicExperienceEntry(experienceId, uid): Promise<BasicExperienceEntryStatus>

Check whether a consumer has already registered for this experience

Parameters

experienceId

string

ID of the Basic Experience

uid

string

Unique identifier for the consumer, typically their email address

Returns

Promise<BasicExperienceEntryStatus>

Whether this consumer has already registered

Example

const entryCheck = await sdk.checkBasicExperienceEntry('experience-id', 'user@example.com');
if (entryCheck.hasEntered) renderAlreadyRegisteredScreen();

checkBasicExperienceItem()

checkBasicExperienceItem(experienceId, itemSlug): Promise<ItemAuthorisationStatus>

Check whether a scanned item belongs to this experience.

A code from another campaign and a code that does not exist are both reported as authorised: false — the response does not distinguish between them.

Parameters

experienceId

string

ID of the Basic Experience

itemSlug

string

Slug of the scanned item, taken from the id query parameter with any leading ! removed

Returns

Promise<ItemAuthorisationStatus>

Whether the item is part of this experience

Example

const auth = await sdk.checkBasicExperienceItem('experience-id', itemSlug);
if (!auth.authorised) renderInvalidCodeScreen();

getBasicExperienceStatus()

getBasicExperienceStatus(experienceId): Promise<BasicExperienceStatus>

Get the status of a Basic Experience (Scan & Register)

Parameters

experienceId

string

ID of the Basic Experience

Returns

Promise<BasicExperienceStatus>

Whether the experience is currently active, and its schedule

Example

const status = await sdk.getBasicExperienceStatus('experience-id');
if (!status.isActive) renderExperienceEndedScreen();

signupForBasicExperience()

signupForBasicExperience(experienceId, entry, images?): Promise<void>

Register a consumer for a Basic Experience (Scan & Register).

Only uid is required; everything else is optional and should only be collected if your form asks for it. Pass itemSlug to have the server re-verify the scanned code as part of the registration rather than relying on an earlier checkBasicExperienceItem call.

Parameters

experienceId

string

ID of the Basic Experience

entry

Omit<BasicExperienceEntry, "images">

Registration details

images?

(Blob | File | Buffer<ArrayBufferLike>)[]

Array of jpeg format images to upload

Returns

Promise<void>

Example

await sdk.signupForBasicExperience('experience-id', {
  uid: 'user@example.com',
  email: 'user@example.com',
  firstName: 'Jane',
  lastName: 'Smith',
  marketingConsent: true,
  extra: {
    productVariant: 'premium-reserve',
  },
});