Wherddocs
HomeDashboard
Getting started

Quickstart

Get Wherd running in your app in ~5 minutes.

1. Get a public key

Sign in to the Wherd dashboard → create a project → Settings → API keys → copy the pk_… key. That's the only credential the SDK needs.

2. Install

React (web)

pnpm add @wherdkit/react

Expo

pnpm dlx expo install @wherdkit/react-native @react-native-async-storage/async-storage
pnpm dlx expo install expo-sensors   # optional — enables shake-to-open

Bare React Native (no Expo)

pnpm add @wherdkit/react-native @react-native-async-storage/async-storage
cd ios && pod install && cd ..   # iOS native deps for AsyncStorage

The SDK is Expo-agnostic — it works in plain React Native with just AsyncStorage. expo-sensors is optional and only powers shake-to-open; if it isn't installed, shake is a no-op and the FAB / programmatic triggers work exactly the same. (You can still add expo-sensors to a bare app via Expo Modules if you want shake.)

3. Mount the provider + widget

import { WherdProvider, MessagesWidget } from "@wherdkit/react"; // or @wherdkit/react-native

<WherdProvider publicKey="pk_…">
  <App />
  <MessagesWidget />
</WherdProvider>

A floating launcher appears. Open it → send a message → it shows up in your dashboard inbox, where you can reply. Done.

4. Identify your users (optional)

Anonymous works out of the box. To attach identity + traits:

<WherdProvider
  publicKey="pk_…"
  user={{ id: "user_123", email: "ada@acme.com", name: "Ada", traits: { plan: "pro" } }}
>

Verified identity (recommended for production)

To prove a user is who they claim (so nobody can spoof another user's id), compute an HMAC on your server with your project secret key and pass it as userHash:

import { createHmac } from "node:crypto";
const userHash = createHmac("sha256", process.env.WHERD_SECRET_KEY)
  .update(user.id)
  .digest("hex");
// send userHash to the client, then:
// user={{ id: user.id, userHash }}

5. Show "What's New" anywhere

import { useWherd, useUnreadChangelog } from "@wherdkit/react";

function WhatsNewButton() {
  const wherd = useWherd();
  const unread = useUnreadChangelog();
  return <button onClick={() => wherd.open("changelog")}>What's new {unread ? `(${unread})` : ""}</button>;
}

Next: Customization · API reference

NextCustomization