React dynamic instances

Public Preview

Dynamic multi-instance for React is currently in public preview.

This guide explains how to implement dynamic multi-instance tracking for React / Next.js.

Requires @seeka-labs/converge and @seeka-labs/converge-react version 1.10.4 or later. See React installation for setup.

Quick start

Your app needs a SeekaProvider at the root with your master instance credentials. See React installation for full setup. Page components rendered inside the provider can then create dynamic instances.

import { SeekaProvider } from '@seeka-labs/converge-react';

// App root - master instance (your platform's Seeka account)
function App() {
    return (
        <SeekaProvider org="your-org-id" id="your-instance-id" publicKey="your-public-key">
            <Router />
        </SeekaProvider>
    );
}

Inside a page component, pass an array of dynamic instance configs to useSeekaConverge. Each instance is created on mount and destroyed on unmount. All .track and .identity calls automatically fan out to the master and every active dynamic instance.

import { useSeekaConverge } from '@seeka-labs/converge-react';

// Page component - rendered inside SeekaProvider
function EventPage({ organiserA, organiserB }) {
    const converge = useSeekaConverge([
        { org: organiserA.orgId, id: organiserA.instanceId, publicKey: organiserA.publicKey },
        { org: organiserB.orgId, id: organiserB.instanceId, publicKey: organiserB.publicKey },
    ]);

    const handlePurchase = (order) => {
        // Fires to master + organiserA + organiserB
        converge?.track.order({
            orderId: order.id,
            totalPrice: order.total,
            currency: order.currency,
        });
    };

    return <button onClick={() => handlePurchase(order)}>Buy tickets</button>;
}

The dynamic instances array can change between renders (e.g. when the user navigates to a different page) and instances are created/destroyed automatically.

Master-only tracking

By default, .track and .identity fan out to all instances. To fire to the master only:

// Fires to master + all dynamic instances
converge?.track.viewPage();

// Fires to master only
converge?.master.track.viewPage();

useSeekaInstance hook

For more control over individual instances (e.g. tracking different events to different brands, handling per-instance ready/error states), use useSeekaInstance directly:

import { useSeekaInstance, useSeekaConverge } from '@seeka-labs/converge-react';

function EventPage({ organiserA, organiserB }) {
    const converge = useSeekaConverge();
    const brandA = useSeekaInstance({
        org: organiserA.orgId,
        id: organiserA.instanceId,
        publicKey: organiserA.publicKey,
    });
    const brandB = useSeekaInstance({
        org: organiserB.orgId,
        id: organiserB.instanceId,
        publicKey: organiserB.publicKey,
    });

    useEffect(() => {
        // Track a different event to each brand
        if (brandA.ready) brandA.instance.track.viewContentItem({ contentId: organiserA.eventId });
        if (brandB.ready) brandB.instance.track.viewContentItem({ contentId: organiserB.eventId });

        // Track to master + all ready dynamic instances
        converge?.track.viewPage();
    }, [brandA.ready, brandB.ready]);

    return <div>{/* page content */}</div>;
}

useSeekaInstance props

Required:

  • org (string) - Organisation ID
  • id (string) - Instance ID
  • publicKey (string) - Public key

Optional:

  • consent (object) - Per-instance consent override (IAB purpose IDs). Omit to inherit from master.
  • seekaHost (string) - Override SDK host. Default: https://sdk.seeka.services
  • timeoutMs (number) - Load timeout in milliseconds. Default: 20000

useSeekaInstance return value

  • instance - SDK proxy with .track and .identity. undefined until ready.
  • ready - true when initialized.
  • error - Set if the instance failed to load within the timeout.

Configuring SeekaProvider context

If your app provides a SeekaProviderConfigContext for the master instance (see React installation), the same context applies when using dynamic instances. Dynamic instances inherit identity and consent from the master, so the provider context only needs to be set once at the root.

import { SeekaProvider, SeekaProviderConfigContext } from '@seeka-labs/converge-react';

const seekaContext: SeekaProviderConfigContext = {
    tracking: {
        defaults: {
            currencyCode: 'NZD',
            countryCode: 'NZ',
        }
    },
    client: {
        ver: '1.0.0',
        type: 'yourplatformname'
    }
};

function App() {
    return (
        <SeekaProvider
            org="your-org-id"
            id="your-instance-id"
            publicKey="your-public-key"
            context={seekaContext}
        >
            <Router />
        </SeekaProvider>
    );
}

Dynamic instances created via useSeekaConverge([...]) or useSeekaInstance({...}) inside this provider will share the master's identity and consent. The context.client fields are sent with the master's events only - dynamic instances report their own client type (iframe/dynamic).

Dynamic instances inherit consent from the master by default. Changes to the master's privacy state (e.g. user updates OneTrust preferences) propagate to all active instances via the Privacy SDK.

To override consent for a specific instance, use useSeekaInstance with the consent prop:

const brand = useSeekaInstance({
    org: '...', id: '...', publicKey: '...',
    consent: { grantedIabPurposeIds: [1, 7], deniedIabPurposeIds: [3, 4] },
});

Example project

Usage

See multi-instance usage for general interaction patterns.