Configuration Parameters

Parameter	Type	Purpose
`partnerId`	`String`	Your Thanks-provided partner id
`statusText`	`String`	The message to display on the Thanks splash screen.
`embeddedInto`	`HTMLElement \| HTMLElement[]`	Providing a HTML element here will enable the embedded Thanks widget (as opposed to the pop-up style widget). The embedded widget will be loaded into the provided element. If using multiple slots on a single page, an array of HTMLElements should be passed.
`ui`	`{ eventName?: string, orderNumber?: string }`	Let's you provide copy that may be used in Thanks UI elements. For example, "Order XYZ is on the way!"
`slot`	`String`	Defines a size constraint for a embedded block.
`email`	`String \| ((factory: {encode: ( email: string \| undefined, ) => Promise<string \| undefined>;}) => Promise<string \| undefined>)`	The customer email. This is hashed and then used for ad matching, and in cases where the customer must be sent a communication we can use it for autofill.Note: if this field is included then `onPersonalInformationRequest` is required.
`emailHash`	`{ sha256: String }`	The pre-hashed version of the customer email. Used only to exclude/include the customer from ads they have seen before.
`allowLocalStorage`	`boolean`	Allows Thanks to store information on publisher's site.
`enabledPersonalInformationSubjects`	`{ relevance?: Boolean, autofill?: Boolean, notification?: Boolean }`	A list of PII subjects that you would like to opt in to. This provides a backwards compatible way for us to introduce new subjects.
`onPersonalInformationRequest`	`(subject: 'relevance' \| 'notification' \| 'autofill', { token: string, advertiser?: string, offerType?: 'coupon' \| 'subscription' \| 'transaction' })' => Promise<PersonalInformation>`	A callback to handle PII requests. Note: this field is required if a field like customer email is included. See below for an example payload and refer to Customer Data for more information.
`customerLocation`	`{ country?: 'US' \| 'AU', postcode?: string }`	The customer's home location. Refer to Customer Data for more information.
`purchaseLocation`	`{ country?: 'US' \| 'AU', postcode?: string }`	The customer's purchase location. Refer Customer Data for more information.
`traceId`	`String`	An id enabling you to track widget activity.
`keywords`	`String[]`	A set of keywords related to this activity.
`categories`	`String[]`	A set of categories related to this activity.
`items`	`CartItem[]`	A set of items purchased during this activity. See below for an example payload. See CartItem reference below for more info
`style`	`{ zIndex?: number, padding?: boolean, overlay?: boolean }`	Web SDK only. Style overrides for the Thanks widget (see Style Overrides below).
`offsetTop`	`() => number`	A callback that provides the pixel value to offset the widget from the top of the screen. Defaults to 100px on desktop web and 70px on mobile web. Web SDK. The callback is re-invoked on every `window` resize event, so the offset can be updated dynamically (e.g. when a sticky header changes height). React Native SDK. The callback is invoked once when the widget initializes and is not re-evaluated. To change the offset after open, use the `wrapperComponent` to control the layout instad.
`onDisplay`	`() => void`	A callback that will be called when the widget displays.
`onClose`	`() => void`	A callback that will be called when the widget is closed.

Cart Item

Field	Type	Required	Description
`name`	`string`	yes	Item name
`category`	`string`	yes	Item category
`value`	`number`	yes	Item price
`currency`	`string`	yes	ISO 4217, e.g. `"AUD"`
`quantity`	`number`	yes	Quantity purchased
`event`	`object`	no	Event details, for ticketing/experience items
`event.id`	`string`	yes (within `event`)	Your event identifier
`event.name`	`string`	no	Event name
`event.category`	`string`	no	Event category, e.g. `"concert"`
`event.venue`	`string`	no	Venue name
`event.startAt`	`string`	no	ISO 8601 start datetime

You may include additional properties on a cart item beyond these.

Please review the examples here

Style Overrides

Parameter	Type	Purpose
`zIndex`	`number`	The z-index applied to the widget iframe. Defaults to `100`. Increase if you have higher-stacked elements (e.g. modals, sticky headers).
`padding`	`boolean`	Mobile viewport only. Set to `false` to remove the default side and top padding around the widget. Defaults to `true`.
`overlay`	`boolean`	Only for the Thanks Splash popup.Set to `false` to remove the semi-transparent shadow behind the widget (useful when your host page already provides its own dimming). Defaults to `true`.

React Native Only

Parameter	Type	Purpose
`onLinkClick`	`(url: string) => boolean`	A callback fired when a link inside the widget is clicked. Return `true` (or omit) to let Thanks open it instead; return `false` to handle it yourself.
`onError`	`(error: ThanksSdkError) => void`	A callback invoked when the widget fails to load, initialize, or encounter a runtime error. The error object includes a code (e.g. HttpError, StartupTimeout, LoadingError, InitialisationFailed, NotEligible, WebviewError, PiiRequestFailed), a human-readable message, an origin of 'widget', and where available context and originalError for debugging.
`wrapperComponent`	`FC<{ children, onRequestClose, animationType?, transparent: true, isReady? }>`	A custom component used in place of React Native's `Modal` to wrap the widget WebView. Use this to control z-index, position, or visibility at runtime. The wrapper is a regular React component, so its own state can re-render and reposition the widget after it's open. Defaults to `Modal`.

Examples

onPersonalInformationRequest

We can also accept additional properties, please contact Thanks if you have additional properties you wish to pass in.

{
  email: "[email protected]",
  firstName: "Emma",
  lastName: "Jackson",
  phoneNumber: "+12025550125",
  dateOfBirth: "2000-09-15",
  age: 25,
  gender: "female"
};

items

Cart items can have any properties you wish to send, as an example:

{
  name: "Colourful stacking glass set",
  category: "gifts",
  value: 49.95,
  currency: "USD",
  quantity: 1
	premium: true
}

However you may have additional properties as you wish.

Event example:

{
  name: 'Tame Impala — Sydney',
  category: 'concert',
  value: 129.95,
  currency: 'AUD',
  quantity: 2,
  event: {
    name: 'Tame Impala',
    venue: 'Qudos Bank Arena',
    startAt: '2026-08-15T19:30:00+10:00',
    location: {
    region: 'NSW',
    city: 'Sydney',
    postcode: '2127',
    country: 'AU', // ISO 3166-1 alpha-2
    latLng: [-33.8475, 151.0637], 
    type: 'physical',
  },
}

Styling and Positioning

`style.zIndex` (web)

zIndex is read once when the widget iframe is created. To raise the widget above other high-stacked elements on the page:

<script>
  __thanks = {
    partnerId: 'YOUR_PARTNER_ID',
    style: { zIndex: 100000 },
  };
</script>

Changes to __thanks.style.zIndex after the widget is open are not picked up. If you need to re-stack the widget at runtime, set a high value up front.

`offsetTop` (web only)

offsetTop is re-evaluated on window resize. If your sticky header height changes without a viewport resize (e.g. it collapses on scroll), dispatch a synthetic resize so the widget re-reads it:

__thanks = {
  partnerId: 'YOUR_PARTNER_ID',
  offsetTop: () => document.querySelector('.site-header').offsetHeight + 20,
};

// after the header height changes:
window.dispatchEvent(new Event('resize'));

`wrapperComponent` (React Native only)

The React Native SDK currently does not honor style.zIndex or runtime offsetTop changes. For runtime control over layering and visibility, e.g. hiding the widget while an in-app browser is open and bringing it back, pass a custom wrapperComponent. It receives onRequestClose, animationType, transparent, and isReady props, and you can hold your own state inside it.

import { useState } from 'react';
import { View } from 'react-native';
import { ThanksWidgetController, thanksWidget } from '@thanksjs/react-native-webview';

const CustomWrapper = ({ children, isReady }) => {
  const [behind, setBehind] = useState(false);

  // expose a setter however suits your app
  globalThis.__setWidgetBehind = setBehind;

  return (
    <View
      style={{
        position: 'absolute',
        top: 0, left: 0, right: 0, bottom: 0,
        zIndex: behind ? -1 : 9999,
        display: isReady ? 'flex' : 'none',
      }}
    >
      {children}
    </View>
  );
};

// Set on the controller…
<ThanksWidgetController
  partnerId="YOUR_PARTNER_ID"
  wrapperComponent={CustomWrapper}
/>;

// …or pass per-open (overrides the controller value):
thanksWidget.open({ wrapperComponent: CustomWrapper });

When you open an in-app browser from onLinkClick, set __setWidgetBehind(true) before opening it and __setWidgetBehind(false) when it closes. The widget stays mounted (preserving customer journey state) but moves out of the way.