SDKs

Use an SDK when a script tag is not a good fit: a web app that you build with npm, or a React Native or Expo app. The SDKs send the same events to the same endpoint as the script, so the dashboard, goals, identify and revenue work the same way.

Both packages have no dependencies and include TypeScript types. Use the SDK or the script on a page, not both, or each page view counts two times.

Web: @twelvebit/web#

npm i https://twelvebit.app/sdk/twelvebit-web.tgz

Call initTwelvebit one time in the browser. It sends a page view at once and on each client-side navigation (pushState, replaceState, back and forward).

import { initTwelvebit, track, identify } from "@twelvebit/web";

initTwelvebit({ siteId: "tb_YOUR_SITE_ID", domain: "example.com" });

track("signup", { plan: "pro" });
identify("user_42", { email: "ann@example.com", name: "Ann" });

The package is safe to import on the server. On the server, every call does nothing. Calls before initTwelvebit wait (at most 50) and run after it.

React and Next.js#

Put the provider in the root layout. It starts the client in the browser after the first render.

// app/layout.tsx
import { TwelvebitProvider } from "@twelvebit/web/react";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <TwelvebitProvider config={{ siteId: "tb_YOUR_SITE_ID", domain: "example.com" }}>{children}</TwelvebitProvider>
      </body>
    </html>
  );
}

"use client";
import { useTwelvebit } from "@twelvebit/web/react";

export function UpgradeButton() {
  const tb = useTwelvebit();
  return <button onClick={() => tb.track("upgrade_click", { plan: "pro" })}>Upgrade</button>;
}

Web options#

Web API#

How it sends: events wait in a queue and go out every 5 seconds or at 10 events, one request per event. When the page is hidden or closed, the queue goes out with sendBeacon. The cookies (_tb_vid 1 year, _tb_sid 30 minutes) and the tracking gates (localhost, automated browsers, localStorage.twelvebit_ignore) are the same as the script.

React Native and Expo: @twelvebit/react-native#

npm i https://twelvebit.app/sdk/twelvebit-react-native.tgz
# Recommended: keeps the visitor id and the offline queue when the app restarts, and sends when the network comes back.
npx expo install @react-native-async-storage/async-storage @react-native-community/netinfo

Without AsyncStorage, the SDK keeps the visitor id and the queue in memory only, so each app start is a new visitor. NetInfo is optional: without it, the SDK retries with backoff.

import { TwelvebitProvider, useTwelvebit, useTwelvebitScreen } from "@twelvebit/react-native";

export default function App() {
  return (
    <TwelvebitProvider config={{ siteId: "tb_YOUR_SITE_ID", appName: "myapp" }}>
      <Home />
    </TwelvebitProvider>
  );
}

function Home() {
  useTwelvebitScreen("Home");
  const tb = useTwelvebit();
  return <Button title="Buy" onPress={() => tb.track("purchase_click", { sku: "pro" })} />;
}

With React Navigation, send each screen from the navigation container:

const ref = useNavigationContainerRef();
const tb = useTwelvebit();

<NavigationContainer ref={ref} onStateChange={() => tb.trackScreen(ref.getCurrentRoute()?.name ?? "unknown")}>

Without React, use the client directly:

import { createTwelvebit } from "@twelvebit/react-native";

const tb = createTwelvebit({ siteId: "tb_YOUR_SITE_ID", appName: "myapp" });
tb.trackScreen("Settings");

How app events look in the dashboard#

• A screen is a page view with the URL app://<appName>/<screen>. The dashboard shows the hostname app and the path /<screen>. Filter on the hostname app to see only app traffic.
• The device is Mobile or Tablet (iPad, and Android with a short side of 600 dp or more). The operating system comes from the User-Agent that the SDK sends: Mozilla/5.0 (…) twelvebit-react-native/0.1 (ios).
• A screen view has no referrer. App traffic shows as Direct.
• The server accepts app:// URLs on every site, so you can use the same site id for your website and your app. To link one person across the two, call identify with the same user id on the web and in the app.

React Native options#

React Native API#

Offline and sessions: events wait in a queue that is kept in storage (at most 200; the oldest go first). A failed request is tried again after 1, 2, 4 … seconds (at most 5 minutes). The server never accepts a 4xx answer, so the SDK drops that event. A session ends after 30 minutes without events or time in the foreground. When the app goes to the background, the SDK sends a ping, so the visit duration includes the time in the app.