Skip to Content
JourneyKit
Integration

Browser SDK

Served from your JourneyKit host at /sdk.js. No dependencies; exposes a global JourneyKit.

<script src="https://journeykit.io/sdk.js"></script>

Use it as a module

In a bundled app (React, Vue, plain TypeScript…) create a client instead of using the global. It has the same identify, track and reset, fully typed, and no shared state.

import { createClient } from "@journeykit.io/browser-sdk";

export const jk = createClient({ key: "jk_pub_…" });

jk.identify("user-123", { email: "ada@example.com" });
jk.track("project_created", { template: "blank" });

createClient takes the same key and host options as init below; host defaults to https://journeykit.io. The contact id is still remembered in localStorage, and a missing or blocked localStorage (SSR, private mode) is tolerated.

init(options)

Must be called first.

OptionTypeDefault
keystring,A public key (jk_pub_…). The SDK warns if you pass anything else.
hoststringorigin of the script tagWhere to send requests.

identify(contactId, properties?)

Tells JourneyKit who the current visitor is and remembers it in localStorage (jk_uid) across page loads.

JourneyKit.identify("user-123", {
  email: "ada@example.com",   // → the contact's email address
  name: "Ada Lovelace",        // → the contact's display name
  firstName: "Ada",            // everything else → contact properties
  plan: "trial",
});

email and name are lifted out and stored on the contact; every other key becomes a contact property. Unknown keys are accepted and appear in Contacts → Properties as undefined until you describe them.

track(event, properties?)

Sends an event for the identified contact. Ignored (with a console warning) if identify hasn't been called.

JourneyKit.track("project_created", { template: "blank" });

Event names: letters, digits, _ . : -, up to 120 characters.

page(properties?)

Records a page_viewed event for the current page, with its path, URL, title, referrer and any utm_ parameters. Call it on each page load, or on each route change in a single-page app.

JourneyKit.page();

Before identify(), page() sends nothing and creates no contact, so anonymous visitors never count against your plan. Instead the browser keeps two things in localStorage:

  • The 20 most recent page views, in jk_page_queue.
  • Where the visitor first came from, in jk_first_touch: the referrer, landing path, utm_ parameters and time of their first anonymous page() call. This is recorded once and never overwritten.

Visits from someone who never identifies stay in their browser and are never sent.

When identify() is called, the SDK sends what it kept:

  • First touch goes on that identify call, once, as the contact properties first_touch_at, first_touch_landing_path, first_touch_referrer and first_touch_utm_* (source, medium, campaign, term and content only, for example first_touch_utm_source).
  • The waiting views go out as page_viewed events, right after the identify call succeeds. Each has a viewed_at property with the time of the visit. The event's own time is when it was sent, because public keys can't set event timestamps. Use viewed_at for when the visit happened.

Views stay in the browser until the server accepts them, and a failed send is retried on the next identify() or page(). If a browser is cut off after the server accepted them, for example by a redirect straight after login, the same views can be sent twice.

First touch is per browser. If a contact identifies in a second browser or on another device after visiting there anonymously, its first touch replaces the first_touch_* values stored on the contact.

A workflow triggered by page_viewed runs for each flushed view, so one identify() can start up to 20 runs for a contact, depending on the workflow's re-entry setting.

reset() clears both, so the next person on a shared browser starts clean.

reset()

Forgets the contact, call it on logout.

On this page