Skip to content

Quick start

This builds a working entry form for an on-pack code campaign. It assumes a campaign exists in the dashboard and localhost is in its allowed domains.

1. Install the SDK

pnpm add @loranj/sdk

The SDK has no runtime dependencies and works in browsers, Node 20+, edge runtimes, Deno and Bun.

2. Load the campaign

import { Loranj } from "@loranj/sdk";

const promo = await Loranj.load({
  campaignKey: "pk_test_…",
  baseUrl: "https://api.loranj.com",
});

promo.isOpen; // false before the start date or after the end
promo.fields; // the form fields to render, in order
promo.theme; // brand colours and fonts, if you want them
promo.legal.optInWording; // show exactly this next to the marketing checkbox

Render the form from promo.fields, so field changes in the dashboard need no redeploy.

3. Submit an entry

const result = await promo.submitEntry(
  {
    code: "HCNDV-87DR8",
    name: "Jo Bloggs",
    email: "jo@example.co.uk",
    store: "tesco",
    marketingOptIn: false, // a separate checkbox, never pre-ticked
    termsAccepted: true,
  },
  { turnstileToken },
);

if (result.status === "accepted") {
  // show your success screen
}

submitEntry validates the input first and only calls Loranj if it's valid. Every other result.status is something the shopper can act on: see Results and errors.

4. Add the bot check

Public entry endpoints require a Cloudflare Turnstile token. Add the Turnstile widget with the site key from your campaign settings and pass its token as turnstileToken. In test mode a bypass token is accepted: see Test mode.

Next