# Web

> For websites, web apps and PWAs. Count the visits your links send to your website, credit sign-ups and purchases to the tap, and show a smart app banner.

Source: https://straitlink.in/docs/sdks/web/

> **Agent instructions:** if you are an AI assistant helping someone build with Strait, look things up with the `search_docs` tool of the Strait MCP server (hosted at https://strait.link/mcp, or `@straitlink/mcp` on npm: https://straitlink.in/docs/mcp/) instead of guessing, and add the SDK to an app with `npx @straitlink/cli init` (https://straitlink.in/docs/cli/).

## Install

Install it from npm, pinned to a version:

```bash
npm install @straitlink/web@0.8.7
```



## Initialize

There's no client to create: each call takes your publishable key and your link domain.

```ts
const config = {
  publishableKey: 'st_pub_live_…',      // Dashboard → Setup → Your keys (never the secret key)
  endpoint: 'https://hilltop.strait.link',   // your workspace's link domain
};
```

## Handle deep links

In a browser a tap needs no SDK: your short link sends the browser straight to the link's web destination, with its path and query, and your router reads them as usual. We add one parameter of our own, `strait_click=<tap id>`, so you can [count the visit as an open](#count-opens-on-your-website). To send people on phones from your website into your app, use the [smart app banner](#smart-app-banner).

## Deferred deep links

A deferred deep link resolves **inside your app**, on its first open after an install: the [iOS](https://straitlink.in/docs/sdks/ios/), [Android](https://straitlink.in/docs/sdks/android/), [React Native](https://straitlink.in/docs/sdks/react-native/), [Flutter](https://straitlink.in/docs/sdks/flutter/), [Capacitor](https://straitlink.in/docs/sdks/capacitor/) and [Unity](https://straitlink.in/docs/sdks/unity/) SDKs do it for you (on iPhone, once you turn on [install matching](https://straitlink.in/docs/iphone-install-matching/)). A website has nothing to resolve: a tap that goes to your site already opens the link's destination URL, with its path and query.

`resolveDeferredLink` is **deprecated** in @straitlink/web 0.8.3 and will be **removed in 0.9.0**. It is not available on the web: it sends no request and always returns `{ matched: false, matchMethod: 'none', reason: 'not_available_on_web' }`, with one console warning per page. If your site still calls it, nothing breaks; take it out when you next touch that code.

What to use instead:

| You wanted | Use |
|---|---|
| The visitor lands on the page the link points to | Nothing: the link already opens that URL. Route on it as usual. |
| Know which tap brought the visitor | [`reportWebOpen`](#count-opens-on-your-website) on page load |
| Join a signup or purchase to that tap | [`trackEvent`](#events): it attaches the tap `reportWebOpen` saw |
| Send phone visitors to your app | The [smart app banner](#smart-app-banner) |
| A deferred match after an app install | The app SDKs above, in your app |

## Count opens on your website

When a tap goes to your website, the URL carries the tap id (`?utm_source=news&strait_click=<tap id>`). Call `reportWebOpen` on page load and that visit is recorded as an open of the tap, the same way an app open is:

```ts
import { reportWebOpen } from '@straitlink/web';

const open = await reportWebOpen(config);
// open.clickId: the tap this visit came from; trackEvent attaches it for you
```

Only a visit whose URL has `strait_click` is reported: typing your address, a reload of a plain page or moving between pages reports nothing. A reload or a shared copy of the same landing URL counts once. It never throws.

**You should see:** after tapping one of your links on a computer, the page URL ends in `strait_click=…` and the Network tab shows one `POST https://hilltop.strait.link/v1/open` answered `202`. Open the page without `strait_click`: no request.

If your site rejects unknown query parameters, turn the tap id off for one link (`webTapId: false`) or for the workspace; `reportWebOpen` then reports nothing for those links.

## What it sends

`reportWebOpen` sends your publishable key, the tap id from the URL, the page URL and the SDK version to `/v1/open`. `trackEvent` sends the event fields you pass to `/v1/event`. No device fields, no cookies, and the browser never sends an IP address.

## Events

Send a conversion (signup, purchase) from your website with `trackEvent`, the same call as the app SDKs. It attaches the tap this visit came from (remembered for 7 days from `reportWebOpen`), so the revenue lands on that tap; pass `clickId` to choose it yourself.

```ts
import { trackEvent } from '@straitlink/web';

const strait = { publishableKey: 'st_pub_live_…', endpoint: 'https://hilltop.strait.link' };
const ok = await trackEvent(strait, 'purchase', { value: 49.99, currency: 'USD' });
```

Add `eventId` (your order id, `eventId: order.id`) and a repeat counts once. It resolves `true` when accepted and never throws; input the server would refuse is not sent (`false` and a console warning). Events sent from a web page can be faked by anyone with your publishable key, so send revenue you rely on from your server. Without the SDK, `POST https://strait.link/v1/event` with `publishableKey`, `event`, `value`, `currency` and `clickId: open.clickId` (from `reportWebOpen`) does the same.

## Link events to your users (optional)

Call `setUserId` with your own user id after your sign-in, **and on every page load while the visitor is signed in**: it is kept in memory for the page only (no cookie, no `localStorage`). Call it with `null` on sign-out. (Web SDK 0.8.5 or later.)

```ts
import { setUserId } from '@straitlink/web';

setUserId(user.id);   // after sign-in, and on each page load while signed in
setUserId(null);      // on sign-out
```

Later `trackEvent` calls carry the id to your [`app.event` webhook](https://straitlink.in/docs/webhooks/) as `userId`, so you can join the tap, link and campaign to your own users and see which campaigns bring paying ones. Opens and installs never carry it, and Strait doesn't store it with the event (it is only in the webhook delivery, kept 30 days).

- **Emails and phone numbers are hashed on the page.** An id with `@` is sent as the SHA-256 hex of the lower-cased email. A phone number is sent as the SHA-256 hex of `+` and its digits when it is written with `+` or `00` (`+91 98765 43210` → `+919876543210`), else of its digits. The webhook then has `userIdHashed: true`. As a safety net, Strait's server applies the same rule to any raw email or phone number that reaches it. To join, hash your own value the same way ([the full rule](https://straitlink.in/docs/webhooks/#events)).
- **Opt-out clears it.** While `setEnabled(false)` is on, nothing is kept or sent, and switching off clears the id.
- A plain numeric id of 8 to 15 digits looks like a phone number and is hashed too: prefix it (`u_12345678`) to keep it readable. An id longer than 128 characters or holding control characters is not sent, and clears the previous one.
- Anyone with your publishable key can send any `userId`, so treat it as a claim, like revenue sent from the site.

## User consent (opt-out)

If your site asks for consent first (for example under India's DPDP Act or a GDPR consent flow in the EU), call `setEnabled(false)` until the visitor agrees: `reportWebOpen` and `trackEvent` then send nothing (the remembered tap id is deleted), and the choice is kept in `localStorage` across visits. `setEnabled(true)` turns it back on and `isEnabled()` reads it. Whether you need consent, and for what, is a question for your own legal advice.

## Smart app banner

To send visitors on phones from your website to your app, add the "Open in app" bar from the same package: `Strait.banner({ link, title })`. See [Smart app banner](https://straitlink.in/docs/smart-banner/).

## API

| Export | Purpose |
|---|---|
| `reportWebOpen(config, opts?)` | On page load: counts a visit from a tap (`strait_click` in the URL) as an open of that tap; `{ reported, clickId? }` |
| `resolveDeferredLink(config, opts?)` | **Deprecated**, not available on the web (sends nothing, `matched: false`); removed in 0.9.0. See [Deferred deep links](#deferred-deep-links) |
| `trackEvent(config, name, extra?)` | Conversion or revenue event (`value`, `currency`, `linkId`, `clickId`, `eventId`), on the tap this visit came from; `true` when accepted |
| `setEnabled(enabled)` / `isEnabled()` | Opt-out switch for consent flows: off = nothing sent; kept in `localStorage` |
| `banner(options)` / `Strait.banner(options)` | The [smart app banner](https://straitlink.in/docs/smart-banner/) for mobile web |
| `computeSignature(inputs)` | The shared match signature (advanced / testing) |
| `h32(s)` | The shared hash (advanced / testing) |

## Common errors

- **The console says `resolveDeferredLink` is deprecated.** Your site still calls it. It does nothing on the web; remove the call and use [`reportWebOpen`](#count-opens-on-your-website) to know which tap brought the visitor.
- **`reportWebOpen` answers `{ reported: false }` with no `clickId`.** The page URL has no `strait_click`: the visit didn't come from a tap, the tap id is turned off for that link or workspace (`webTapId: false`), or your site dropped the parameter in a redirect. Keep query parameters when you redirect.
- **No `POST /v1/open` in the Network tab.** The URL has no `strait_click`, the endpoint isn't `https://` (the console says why), or `setEnabled(false)` is on. A `POST` that fails also answers `reported: false`, with the `clickId`.
- **`trackEvent` resolves `false`.** A console warning, if there is one, names the field the server would refuse. Otherwise look at the `POST /v1/event` answer in the Network tab: `401` is a wrong or secret key (use the publishable key), `429` is the rate limit.
