React SDK

Disco's React SDK shows Disco offers inside a React web app. Add one <DiscoRecommendations> component where you want offers to appear, pass your public API key and the order details, and Disco handles the rest.

This SDK is for React apps that run in the browser. Building a mobile app in React Native? Use the React Native SDK instead. They are separate packages with different props.

DiscoBeat channel partners: one key per publisher

Offers serve per publisher, so pass each publisher's own ad-serving key as apiKey, created when Disco approves that publisher. Creating publishers and managing their keys is covered by Channel Management and the Channel API.

Get access

The React SDK is a private package. It isn't published to the public npm registry, so npm install or pnpm add will not find it until your project is configured to reach Disco's registry.

Contact your Disco team to request access. They'll provide an npm token and the registry settings your project needs. Once those are in place, the install steps below work as written.

Install

npm install @disconetwork/react@latest

Always install the latest version, and don't pin a version number. New formats and fixes ship in new releases.

The SDK works with React 18 and React 19.

1. Set up a widget

Every placement starts with a widget in the Disco dashboard. The widget holds the format and slot settings for that placement, and your code tells Disco which one to load by passing its widget_id.

1. In the Disco dashboard, create a widget for the page you're adding offers to.
2. Choose the format:
   • Inline: offers sit in the normal flow of your page.
   • Bottom drawer: the Essential Pull-up widget, a drawer anchored to the bottom of the screen, designed for mobile screens.
3. Copy the widget's ID. You'll pass it as widget_id in the next step.

Reporting is broken down by widget and by page type, so set up a separate widget for each placement you want to see on its own.

2. Add the component

Render <DiscoRecommendations> where you want offers to appear, once the order details are ready.

import { DiscoRecommendations } from "@disconetwork/react";

export function OrderConfirmation() {
  return (
    <div className="recommendations">
      <DiscoRecommendations
        apiKey="YOUR_PUBLIC_API_KEY"
        payload={{
          email: "customer@example.com",
          page_type: "ORDER_STATUS",
          display_mode: "INLINE",
          order_id: "order-123",
          widget_id: "YOUR_WIDGET_ID",
          cost: "49.99",
          purchases: [
            { product_id: "coffee-001", name: "Coffee", quantity: 1 },
          ],
        }}
      />
    </div>
  );
}

The more shopper and order context you pass, the more relevant the offers Disco can return.

Bottom drawer

To show offers in a bottom drawer, set up the Essential Pull-up widget (step 1), pass its ID as widget_id, and set display_mode to "PULLUP":

<DiscoRecommendations
  apiKey="YOUR_PUBLIC_API_KEY"
  payload={{
    email: "customer@example.com",
    page_type: "ORDER_STATUS",
    display_mode: "PULLUP",
    order_id: "order-123",
    widget_id: "YOUR_PULLUP_WIDGET_ID",
  }}
/>

Props

DiscoRecommendations takes exactly two props. Both are required.

Prop	Type	Required	Description
apiKey	string	✓	Your public Disco API key. DiscoBeat channel partners pass the publisher's key.
payload	DiscoPayload	✓	The shopper, order and placement details for this page. See Payload fields.

There are no callback props, styling props, or ref. Extra props passed from JavaScript are ignored. For spacing or a class name, style the element you wrap the component in.

Payload fields

Placement fields

Field	Type	Details
widget_id	String	ID of the widget you set up in the Disco dashboard
display_mode	String	"INLINE" or "PULLUP" (bottom drawer)
page_type	String	The page the offers appear on, for example "THANK_YOU" or "ORDER_STATUS"

Shopper and order fields

Field	Type	Details
email	String	Plain-text email. Provide email or email_hash
email_hash	String	SHA-256 hash (lowercased, trimmed). Provide email_hash or email
first_name	String	Shopper first name
last_name	String	Shopper last name
phone	String	Phone number
order_id	String or number	Unique order identifier
cost	String or number	Total order cost
purchases	Array	Purchased items (see below)
shipping	Object	Shipping address
billing	Object	Billing address

Purchase item fields

Field	Type	Details
product_id	String or number	Unique product ID
name	String	Product name
type	String	Product category
description	String	Product description
quantity	String or number	Quantity purchased

Address fields (used for both shipping and billing)

Field	Type	Details
zip	String	ZIP or postal code

TypeScript

Alongside the component, the package exports these types: DiscoRecommendationsProps, DiscoPayload, DiscoPurchase, and DiscoAddress.

import {
  DiscoRecommendations,
  type DiscoPayload,
} from "@disconetwork/react";

When the widget loads and reloads

• Mount the component once the API key and order details are ready. Both are read when the component first mounts.
• Re-renders don't restart it. Changing apiKey or payload on a mounted component has no effect.
• To start a new order or route, remount it. Change the component's React key, or unmount and mount it again.
• Unmounting cleans up. It cancels pending work and releases resources. A later mount can use a different payload or API key without reloading the page.
• React Strict Mode is safe. Strict Mode's double run in development does not load the widget twice.

Before you go live

Your Disco team verifies that test requests arrive complete before anything goes live.

Related

• React Native SDK: for React Native mobile apps
• Web SDK: add offers to any web page with a script tag
• App SDK (iOS & Android): the native mobile integration