> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sendrealm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Web Push Setup

> Configure Sendrealm Web Push and register browser subscriptions with the React SDK.

Sendrealm Web Push uses native browser Push API subscriptions and VAPID keys.

## Requirements

* A Sendrealm Push App with the Web provider active.
* A React, Vite, or Next.js app served over HTTPS. Localhost works for development.
* The Sendrealm service worker served from the same origin as your app.
* A permission prompt triggered from a user gesture, such as clicking an Enable notifications button.

## Activate The Web Provider

Open your Push App provider settings in the dashboard. The Web provider stores Sendrealm-managed VAPID keys. Copy the public key only if you need to inspect browser subscriptions manually; the React SDK receives it from `/v1/init`.

If keys are missing, click Activate provider. Use Regenerate keys only when you intentionally want browsers to create fresh subscriptions.

## Install The SDK

```bash theme={null}
npm install @sendrealm/react
```

Copy the service worker:

```bash theme={null}
cp node_modules/@sendrealm/react/sendrealm-service-worker.js public/sendrealm-service-worker.js
```

## Initialize React

```tsx theme={null}
import { useEffect } from "react";
import { init } from "@sendrealm/react";

export function App() {
  useEffect(() => {
    void init({
      appId: "YOUR_SENDREALM_PUSH_APP_ID",
      autoRequestPermission: false,
    });
  }, []);

  return (
    <>
      {/* your app */}
    </>
  );
}
```

Keep `autoRequestPermission` false unless your UX already guarantees initialization runs from a user action. Browsers can block permission prompts that are not user-initiated.

`init()` is idempotent and safe under React StrictMode duplicate effects. The package also exports `SendrealmProvider` for advanced custom-client cases, but it is not required for normal React, Vite, or Next.js apps.

## Add A Prompt Button

```tsx theme={null}
import { useSendrealmSubscription } from "@sendrealm/react";

export function NotificationButton() {
  const { subscribed, optIn, optOut } = useSendrealmSubscription();

  return (
    <button onClick={() => (subscribed ? optOut() : optIn())}>
      {subscribed ? "Disable notifications" : "Enable notifications"}
    </button>
  );
}
```

After opt-in, the SDK sends the full `PushSubscription.toJSON()` payload to Sendrealm and links it to the current device.

## Link Signed-In Users

```ts theme={null}
import { getSendrealmClient } from "@sendrealm/react";

const sendrealm = getSendrealmClient();

await sendrealm.login("user_123", "user@example.com");
await sendrealm.addTags({ plan: "pro", locale: "en-US" });
```

You can then target web devices by `device_ids`, `contact_ids`, `external_ids`, `emails`, audiences, or `platforms: ["web"]` from the API.

## Next.js Notes

Call `init()` from a Client Component and put the service worker file under `public/`.

```tsx theme={null}
"use client";

import { useEffect } from "react";
import { init } from "@sendrealm/react";

export function SendrealmInit() {
  useEffect(() => {
    void init({
      appId: "YOUR_SENDREALM_PUSH_APP_ID",
      autoRequestPermission: false,
    });
  }, []);

  return null;
}
```

Render `<SendrealmInit />` once near your root layout or app shell.

## iOS Notes

iOS Web Push works only for installed Home Screen web apps. Your site must be HTTPS, provide a valid web app manifest, and ask for permission from a user gesture inside the installed PWA.

## Full SDK Reference

See [React Web Push SDK](/sdks/react) for hooks, diagnostics, launch URLs, image support, notification event listeners, and the complete client API.