@c15t/react 3.2.0-canary.0 → 3.2.0

package/docs/integrations/rb2b.md

@@ -0,0 +1,363 @@
+---
+title: RB2B
+description: Load RB2B only after marketing consent with the c15t rb2b helper,
+  and check its loader URL, page views and revocation.
+seoTitle: RB2B consent with c15t
+seoDescription: Load RB2B visitor identification only after marketing consent
+  with c15t, with domain setup, loader URL rules and page-view guidance.
+icon: radar
+group: integrations
+---
+
+RB2B identifies the companies and US visitors behind your site traffic for
+sales outreach. The c15t `rb2b` helper keeps RB2B off the page until
+`marketing` consent is granted. RB2B has no documented stop API, so on
+withdrawal c15t reloads the page to stop it.
+
+## Configure RB2B
+
+Authorize your domain first. Open [Script in RB2B](https://app.rb2b.com/script),
+choose **Add a Domain**, enter the site's domain and save it. RB2B's script
+doesn't run on domains you haven't added. A root domain includes its
+subdomains; an individual hostname authorizes only that hostname.
+
+Copy the account key from Script Setup, where the snippet calls `reb2b.load`.
+This helper uses marketing consent even though some RB2B guidance calls its
+cookies functional. Remove the direct snippet and any tag manager copy so they
+can't bypass c15t.
+
+| Package manager | Command                          |
+| :-------------- | :------------------------------- |
+| npm             | `npm install @c15t/integrations` |
+| pnpm            | `pnpm add @c15t/integrations`    |
+| yarn            | `yarn add @c15t/integrations`    |
+| bun             | `bun add @c15t/integrations`     |
+
+```ts title="src/consent-scripts.ts"
+import { rb2b } from '@c15t/integrations/rb2b';
+
+export const scripts = [rb2b({ accountKey: 'YOUR_RB2B_KEY' })];
+```
+
+## Register the scripts
+
+Complete your [framework quickstart](https://c15t.com/docs/frameworks) first. Keep its Inth
+endpoint, policy, styles and consent UI. Remove the vendor's original script,
+SDK initializer or tag-manager entry, so the vendor loads only through c15t.
+
+The vendor pages put the helper in `src/consent-scripts.ts`. If your framework
+quickstart already has a `scripts` array, such as the one in `c15t.config.ts`
+in the Next.js guide, add the helper to that array instead of creating a
+second file.
+The `scripts` export is a configuration, not an initializer. Add it to the c15t provider you already have, at the registration
+point for your framework below. These are edits to that provider, not a second
+provider.
+
+**Next.js**
+
+Add the configuration to `scripts` in `c15t.config.ts`, next to
+`next.config.ts`:
+
+```ts title="c15t.config.ts"
+import { defineConsentConfig } from 'c15t/next';
+import { scripts } from './src/consent-scripts';
+
+export default defineConsentConfig({ scripts });
+```
+
+Keep the rest of your config, such as `mode` and `routePrefix`, in the
+same call. `ConsentRoot` reads the config in the browser, so the layout
+keeps passing only `state`. App Router, Pages Router and static export all
+read the same file. See
+[Next.js scripts and embeds](https://c15t.com/docs/frameworks/next/scripts).
+
+**TanStack Start**
+
+Import the configuration into your root route and pass it to the existing
+`ConsentRoot` as a top-level prop. Keep the loader from the
+[TanStack Start quickstart](https://c15t.com/docs/frameworks/tanstack-start/quickstart):
+
+```tsx title="src/routes/__root.tsx"
+import { scripts } from '../consent-scripts';
+
+<ConsentRoot state={consent} scripts={scripts}>
+```
+
+Import vendor helpers in the root route module, not in a server function.
+A server function's return value must be serializable, and script
+configurations carry callbacks. See
+[TanStack Start scripts](https://c15t.com/docs/frameworks/tanstack-start/scripts).
+
+**React**
+
+Add the configuration to the existing `ConsentProvider` options, next to
+`mode`:
+
+```tsx title="src/consent.tsx"
+import { scripts } from './consent-scripts';
+
+<ConsentProvider options={{ mode, scripts }}>
+```
+
+`mode` is the `manifest()` value from the
+[React quickstart](../frameworks/react/quickstart.md). Keep the banner,
+dialog and preferences link inside the provider. See
+[React scripts and embeds](../frameworks/react/scripts.md).
+
+**Nuxt**
+
+Register the scripts under the `c15t` key in `app/app.config.ts`. Adjust the
+relative import to where you created `consent-scripts.ts`:
+
+```ts title="app/app.config.ts"
+import { scripts } from '../src/consent-scripts';
+
+export default defineAppConfig({
+  c15t: { scripts },
+});
+```
+
+The Nuxt module merges this over its options in `nuxt.config.ts` and starts
+one script loader in the browser after hydration, once it has applied the
+visitor's stored choice and privacy signals. Keep `scripts` out of
+`nuxt.config.ts`, which reaches the browser as JSON and drops the vendor
+callbacks. Write the vendor IDs into `consent-scripts.ts`. See
+[Nuxt scripts and embeds](https://c15t.com/docs/frameworks/nuxt/scripts).
+
+**Vue**
+
+Pass the scripts to the existing `c15tVue` plugin call in `src/main.ts`:
+
+```ts title="src/main.ts"
+import { c15tVue, manifest } from 'c15t/vue/vue-plugin';
+import { scripts } from './consent-scripts';
+
+app.use(c15tVue, {
+  mode: manifest(),
+  scripts,
+});
+```
+
+Keep your existing `mode` and other options. The plugin starts one
+script loader when the app mounts, after it has applied the visitor's stored
+choice. Do not also call `createScriptLoader` from a component. See
+[Vue scripts and embeds](https://c15t.com/docs/frameworks/vue/scripts).
+
+**Astro**
+
+Add the scripts to the client entrypoint from the
+[Astro quickstart](https://c15t.com/docs/frameworks/astro/quickstart), `src/c15t.client.ts`,
+which the integration finds on its own. Keep `astro.config.mjs` as it is.
+If the module already exports scripts, combine the two arrays.
+
+```ts title="src/c15t.client.ts"
+import type { C15tClientOptionsExtension } from 'c15t/astro';
+import { scripts } from './consent-scripts';
+
+export default { scripts } satisfies C15tClientOptionsExtension;
+```
+
+Vendor helpers contain callbacks, and the integration options in
+`astro.config.mjs` are serialized into the page, so do not put helpers in
+the integration's `scripts` option. The integration passes the client
+entrypoint to the one runtime every page shares, including across
+`ClientRouter` navigation.
+
+**Svelte**
+
+Import the scripts in the component that owns your existing provider and
+pass them as a top-level prop:
+
+```svelte title="src/App.svelte"
+<script lang="ts">
+  import { ConsentProvider, manifest } from 'c15t/svelte';
+  import { scripts } from './consent-scripts';
+</script>
+
+<ConsentProvider mode={manifest()} {scripts}>
+  <!-- Keep your application, consent UI and preferences link here. -->
+</ConsentProvider>
+```
+
+Retain the styles and consent UI from the [Svelte quickstart](https://c15t.com/docs/frameworks/svelte/quickstart).
+The provider owns the loader and disposes it on unmount.
+
+**SvelteKit**
+
+Add the scripts to the existing `ConsentRoot` in the root layout. Keep the
+handle and the layout load from the [SvelteKit quickstart](https://c15t.com/docs/frameworks/sveltekit/quickstart).
+
+```svelte title="src/routes/+layout.svelte"
+<script lang="ts">
+  import { ConsentRoot } from 'c15t/svelte';
+  import { scripts } from '../consent-scripts';
+
+  let { children, data } = $props();
+</script>
+
+<ConsentRoot state={data.consent} {scripts}>
+  {@render children()}
+  <!-- Keep your consent UI and preferences link here. -->
+</ConsentRoot>
+```
+
+Import vendor helpers in the layout component, not in `+layout.server.ts`:
+a server load cannot send functions to the browser. Prerendered, static and
+SPA-mode pages use the same `scripts` prop. If you pass an externally owned
+`runtime` to the provider, register scripts when creating that runtime instead.
+
+**HTML**
+
+The helpers in `@c15t/integrations` are ES modules that need a bundler. On a
+page that loads the c15t script tag, paste the vendor's own snippet instead
+and keep it inert until its category is allowed:
+
+```html
+<script type="text/plain" data-c15t-category="measurement">
+  // The vendor's snippet, unchanged
+</script>
+```
+
+Use the category this guide names for the vendor. c15t runs the snippet
+once that category is allowed, and reloads the page when the visitor
+withdraws it. Helper options on this page, such as `loadMode`, do not apply
+to a pasted snippet. See [HTML scripts](https://c15t.com/docs/frameworks/html/scripts).
+
+**JavaScript**
+
+Pass the scripts to `init()` from `@c15t/browser`, next to your mode:
+
+```ts
+import { init, manifest } from '@c15t/browser';
+import { scripts } from './consent-scripts';
+
+const consent = init({
+  mode: manifest(),
+  scripts,
+});
+```
+
+Keep the mode from your quickstart. With
+`createConsentRuntime` from `c15t/runtime`, pass `scripts` to it instead.
+A kernel you create yourself needs a loader from
+`c15t/modules/script-loader`. Attach one loader per kernel. See
+[JavaScript scripts](https://c15t.com/docs/frameworks/javascript/scripts).
+
+## Options
+
+| Option       | Default                                                    | Behavior                                                                                                                      |
+| ------------ | ---------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `accountKey` | Required                                                   | Public account key, trimmed and URL-encoded. Invalid or blank values log an error and skip loading.                           |
+| `scriptUrl`  | `https://ddwl4m2hdecbv.cloudfront.net/b/<key>/<key>.js.gz` | Override for the URL in your dashboard snippet. Blank values use the default. Unsupported URLs log an error and skip loading. |
+
+Supported HTTPS prefixes are `ddwl4m2hdecbv.cloudfront.net/b/`,
+`s3-us-west-2.amazonaws.com/b2bjsstore/b/` and
+`b2bjsstore.s3.us-west-2.amazonaws.com/b/`. The account segment in the URL
+pathname must appear immediately after the supported base path and match the
+`accountKey` exactly after percent-decoding once. Account keys are
+case-sensitive; percent-escape hex digits can use either case. The pathname
+must end with a nonempty filename after the account separator. Custom
+filenames, including extensionless names, are allowed, as are query strings
+and fragments. A query or fragment cannot supply the filename. An unchanged
+SDK served from an arbitrary proxy fails RB2B's check of
+`document.currentScript.src`.
+
+## Loading and revocation
+
+After consent, the helper loads the account script asynchronously. It defines
+no `reb2b` global or queue before that script runs. The account script creates
+`window.reb2b` itself and ignores calls queued before it runs, so don't add
+your own `reb2b` stub to send `identify` or `collect` calls early. The helper
+sends no identification calls and sets no `rb2bConfig`.
+
+RB2B can delay startup by three seconds. It sends once per script execution.
+
+The loader stays registered across withdrawal and regrant to avoid duplicate
+execution. RB2B has no documented stop or opt-out API. Keep c15t's default page
+reload on revocation enabled. With reload disabled, existing timers, identity
+lookups and tracking can continue until navigation, including an in-flight
+load. The reload doesn't clear RB2B's storage.
+
+CSP depends on account configuration. Observed hosts include the account's
+CloudFront or S3 loader, `b-code.liadm.com`, `pro.ip-api.com`,
+`a.usbrowserspeed.com`, `alocdn.com` and account-specific
+`*.execute-api.us-west-2.amazonaws.com` endpoints.
+
+## Page views in client-routed apps
+
+[RB2B's installation guide](https://support.rb2b.com/en/articles/10126115-installing-your-rb2b-tracking-script)
+asks modern apps to run its script on every page view. This helper runs once
+per page load and does not rerun on client-side route changes.
+
+To count a new page view, use full-page navigation, such as a plain
+`<a href="/pricing">`. In Next.js, use the native anchor instead of
+`next/link` for these links. In Vue or Nuxt, use a native anchor instead of a
+router link. For a button or other imperative navigation, call
+`window.location.assign('/pricing')` from its click handler.
+
+Register c15t and the same `rb2b` configuration on every destination. Keep the
+framework quickstart's consent persistence. On each new page, c15t checks
+marketing permission and any vendor choice before it loads the SDK. Visitors
+who deny permission can still navigate; RB2B stays blocked on their
+destination pages.
+
+Full-page navigation resets page-local application state. Hash-only changes
+and back/forward cache restores don't load a new page, so they don't produce
+a new RB2B page view. If you keep client-side navigation, this helper covers
+only the initial page load. Don't change `accountKey` or `scriptUrl`, delete
+`window.reb2b`, or call `reb2b.collect()` in a route hook to force another page
+view. The observed SDK freezes its client and keeps per-execution state; safe
+teardown and reinitialization have not been verified.
+
+## Cookies and storage
+
+RB2B documents `_reb2bgeo`, `_reb2bloaded`, `_reb2bref`, `_reb2sessionID`,
+`_reb2buid`, `_reb2bfxf`, `_reb2btd`, `_reb2bli`, `_reb2bresolve` and `_reb2butk`.
+Served scripts can differ, including `_reb2bsessionID`, `_reb2bsha`, `_reb2bec`
+and `_reb2beid`. Some builds mirror `_reb2buid`, `_reb2bref`, `_reb2bec`,
+`_reb2butk` and `_reb2beid` in local storage. Check the current account script
+rather than treating this list as exhaustive.
+
+## Verify RB2B
+
+In a fresh browser profile, deny consent and allow only an unrelated category.
+Confirm that no vendor requests, `reb2b` global, cookies, local storage or
+session storage appear. Grant `marketing` and check the loader URL against
+your account snippet. Withdraw consent and confirm the page reloads. RB2B must
+stay blocked on the new page. Inspect storage in DevTools as well as Network.
+
+The scheduled monitor uses a fake account key and checks consent gating and
+loader reachability only. An access-denied response can pass that check. It
+does not verify SDK execution, domain authorization or visitor identification.
+Collection remains blocked in the monitor.
+
+Sources: [RB2B TypeScript installation](https://support.rb2b.com/en/articles/9503690-rb2b-install-guide-for-typescript),
+[cookie information](https://support.rb2b.com/en/articles/9910029-rb2b-cookie-information),
+[consent guidance](https://support.rb2b.com/en/articles/9611828-considerations-when-controlling-rb2b-s-functionality-with-your-cookie-policy-banner),
+and [Next.js installation](https://support.rb2b.com/en/articles/9116902-rb2b-install-guide-for-next-js).
+
+Test in a private window with an opt-in policy. Open DevTools Network, disable
+the cache and filter by the vendor's domain:
+
+1. Load the page. No request goes to the vendor before you choose.
+2. Click Reject, then reload. There is still no vendor request.
+3. Open Privacy settings and allow the helper's category. The vendor script
+   loads without a page reload.
+4. Turn the category off again and save. c15t reloads the page, and the new
+   page makes no vendor request.
+
+c15t reloads on revocation because removing a script element does not stop
+code that already ran. The vendor's listeners, timers and queued events stay
+alive until the page unloads. If you set `reloadOnConsentRevoked: false`, stop
+the vendor yourself. Register a callback-only script whose `onConsentChange`
+calls the vendor's opt-out API, as shown in
+[custom integrations](./building-integrations.md), and check the
+permission before each of your own event calls. The reload does not delete
+cookies the vendor already set; see
+[clear on revocation for your framework](./overview.md#vendor-switches-and-cookie-cleanup).
+
+The helper lists its vendor by name in the preference dialog, so a visitor can
+turn it off inside an allowed category. See
+[vendor consent for your framework](./overview.md#vendor-switches-and-cookie-cleanup). The
+[consent verification guide](../guides/verify-consent.md) covers navigation,
+expiry and hosting checks.