Getting Started

Use the io.tt SDK to create a connected packaging experience — turning a QR or NFC scan on a physical product into a fully interactive consumer journey. Four consumer experience types are available, giving you the ability to build and deploy competitions, loyalty programmes, instant-win mechanics, and gifting flows without needing to build complex back-end code or manage your own databases.

You have two options for how to use this:

• io.tt Experience Templates — out-of-the-box hosted experiences configured entirely in the io.tt dashboard, with no custom code required. Please contact your io.tt account manager to access this.
• Custom front-end — use this SDK to connect your own front-end to io.tt's back-end, with full control over UI and UX. The SDK handles authentication, entry validation, image uploads, and all API communication.

Please contact your io.tt account manager to access either the templates or SDK key.

The SDK ships as a typed npm package (ESM, CJS, and TypeScript definitions included) and works with any modern JavaScript framework — React, Next.js, Vue, or plain browser JS.

Experience Types

For a simpler experience focused on scan-and-register without prize mechanics or loyalty, see the Scan & Register guide.

All registration and signup data is automatically routed to your configured CRM. See the CRM Integration Guide.

To generate and distribute the product codes that power these experiences, see the Supply Chain Guide.

1. Get Your API Key

Log into https://dashboard.io.tt and create a new Experience. Each Experience is paired with a unique SDK API key. The API key is scoped to a single experience — do not share keys between experiences.

2. Install the SDK

npm install @io-tt/sdk

3. Initialise the SDK

Create a single SDK instance and reuse it for the lifetime of the page. There is no need to re-initialise between calls.

Client-side:

import { IOTT } from "@io-tt/sdk";

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

Server-side (e.g. in Next.js API routes or middleware) — pass the user's IP and user agent to improve analytics accuracy:

import { IOTT } from "@io-tt/sdk";

const sdk = new IOTT({
  apiKey: "your-api-key",
  userAgent: req.headers["user-agent"],
  userIP: req.ip
});

React Context Provider — recommended for React apps to avoid re-initialising on every render:

import { IOTT } from "@io-tt/sdk";
import { createContext, useContext, useMemo } from "react";

const IOTTContext = createContext<IOTT | undefined>(undefined);

export function IOTTProvider({ apiKey, children }) {
  const sdk = useMemo(() => new IOTT({ apiKey }), [apiKey]);
  return <IOTTContext.Provider value={sdk}>{children}</IOTTContext.Provider>;
}

export function useIOTT() {
  const sdk = useContext(IOTTContext);
  if (!sdk) throw new Error("useIOTT must be used within an <IOTTProvider>");
  return sdk;
}