Javascript SDK

Overview

The Journify JavaScript SDK enables you to send tracking data from a website to Journify.io backend.

Installation

Npm package

Use one of the following commands to install the Journify SDK:

npm install @journifyio/js-sdk

HTML page

Paste this snippet into the <head> tag of your site to install Journify SDK:

<script>
    !(function () {var journify = (window.journify = window.journify || []);var localJournify; if (!journify.load) { if (journify.invoked) { console.error("Journify snippet included twice."); } else { journify.invoked = !0; journify.methods = ["track", "identify", "group", "track", "page", "updateConsent", "fromGoogleConsentV2"]; journify.factory = function (methodName) { return function () { var callArgs = Array.prototype.slice.call(arguments); callArgs.unshift(methodName); journify.push(callArgs); return journify }; }; for (var i = 0; i < journify.methods.length; i++) { var methodName = journify.methods[i]; journify[methodName] = journify.factory(methodName); } journify.load = function (loadSettings) { var script = document.createElement("script"); script.type = "text/javascript"; script.async = !0; script.src = "https://static.journify.io/@journifyio/js-sdk@latest/journifyio.min.js"; localJournify = journify; script.onload = function () { window.journify.load(loadSettings); for (var i = 0; i < localJournify.length; i++) { var callArgs = localJournify[i]; var methodName = callArgs.shift(); if (!window.journify[methodName]) return; window.journify[methodName].apply(this, callArgs); } }; var firstScript = document.getElementsByTagName("script")[0]; firstScript.parentNode.insertBefore(script, firstScript); };
        journify.load({ writeKey: "<YOUR_WRITE_KEY>" });
    }}})();
</script>

This snippet loads Journify SDK onto the page asynchronously, so it won’t affect your page load speed.

Next, replace <YOUR_WRITE_KEY> with the Write Key you can find in the Journify app. You can find your testing and production Write Keys from the source page on the Journify app.

Initialization

Npm package

If you used the npm package to install Journify, you need to import the SDK on your project and initialize it with your Write Key.

import * as journify from "@journifyio/js-sdk";

journify.load({ writeKey: "<YOUR_WRITE_KEY>" })

Next, replace <YOUR_WRITE_KEY> with the Write Key you can find in the Journify app. You can find your testing and production Write Keys from the source page on the Journify app.

For the full list of available options, see the journify.load reference below

HTML page

If you used the HTML <head> tag to install Journify, you do not need to do anything else. The SDK is already loaded and ready to use.

API

Identify

Good to know

For any of the different methods described in this page, you can replace the properties and traits in the code samples with variables that represent the data collected.

The identify method is how you tell Journify who the current user is. It includes a unique User ID, and any optional traits you know about them. You can read more about it in the identify method reference.

Here’s what a basic call to identify might look like:

journify.identify("john-uuid", {
  fistname: "John",
  lastname: "Doe",
  email: "[email protected]"
});

That identifies John by his unique User ID (in this case john-uuid, which is what you know him by in your database) and labels him with firstname , lastname and email traits.

Page

The page method is how you tell Journify that a user has visited a page. You just need to add the following line to each page you want to track:

journify.page();

You can add the page name and some properties, you can read more about it in the page method reference.

Track

The track method is how you tell Journify about the actions your users are performing on your site. Every action triggers what we call an “event”, which can also have associated properties.

You can read more about track in the track method reference.

Here’s what a track call might look like when a user signs up:

journify.track("Signed Up", {
  plan: "Premium"
});

That tells us that your user triggered the Signed Up event, and chose your hypothetical Premium plan. Properties can be anything you want to record, for example:

journify.track("Book purchased", {
  title: "The Wealth of Nations",
  author: "Adam Smith"
});

To get started, we recommend that you track just a few important events. You can always add more later!

References

Load

Here is an example of a load call with a Write Key and cookie domain:

import * as journify from "@journifyio/js-sdk";

journify.load({
    writeKey: "wk_3MMlPlwRd2XRYjdU2Fa5V334z",
    options: {
       cookie: {
            domain: "app.journify.io"
        }
    }
 
})

As you can notice, the load call takes a JS object as argument, the expected fields on this object are the following:

Field

Type

Required

Description

Default

writeKey

String

Yes

The write key to use

cdnHost

String

The CDN where to load static files

https://static.journify.io

apiHost

String

The API endpoint to which the events are sent.

https://t.journify.io

options.enableHashing

Bool

Whether to enable hashing for user identifiers

false

options.sessionDurationMin

Number

The number of minutes each session takes before we clear UTM tags stored in cookies

options.cookie.domain

String

The domain to use when setting cookies (check this page for more details about Cookie.domain)

current domain

options.autoCapturePII

Bool

Whether to automatically capture PII.

false

options.initialConsent

Object

Initial consent preferences applied before any events are sent. Keys are lowercase category names (advertising, analytics, functional, marketing, personalization); values are "GRANTED", "DENIED", or "UNSPECIFIED". If omitted, all categories default to "UNSPECIFIED" and fall back to the active consent mode. See Consent Management for details.

all UNSPECIFIED

options.autoCapturePhoneRegex

String

The regular expression used to capture phone number

/^[+]?[(]?[0-9]{3}[)]?[-\s.]?[0-9]{3}[-\s.]?[0-9]{2,6}$/

options.phoneCountryCode

String

The country code of the phone number (ex. 212, 966, 970)

options.httpCookieServiceOptions.renewUrl

String

Yes

The url of the cookie keeper service

options.httpCookieServiceOptions.timeout

Number

The number of milliseconds to wait for the request

3000

options.httpCookieServiceOptions.retries

Number

How many times the request will be retried in case of failure

options.httpCookieServiceOptions.backoff

Number

The number of milliseconds to wait before retrying the request

300

options.httpCookieServiceOptions.enablePolling

Bool

Whether to poll for cookie changes

false

options.httpCookieServiceOptions.pollingInterval

Bool

The polling interval in milliseconds

300

You can find your testing and production Write Keys from the source page on the Journify app.

The testing Write Key is used to simulate sending events without processing them, the production Write Key is the one you should use in your app.

You can also add a cookie's domain if you want to prevent other domains from accessing cookies of the current subdomain. In the example above, a user identified on app.journify.io won't be identified on journify.io (A new anonymous id and session will be generated).

The cookie domain might be beneficial if you want to separate users from one subdomain to another, for example, separate users on fr.journify.io from users on en.journify.io.

Identify

Here is an example of an identify call:

journify.identify("2bcc0d81281b", {
  name: "Adam Smith",
  email: "[email protected]",
  plan: "enterprise"
});

As you can notice, the identify call takes the following arguments:

Argument

Type

Required

Description

user ID

String

Yes

Unique identifier for the user in your business (e.g: database id, email, phone). See the Identities doc for more details.

externalIDs

Object

An object of additioal third party identifiers. (keys include but not limited to: facebook_browser_id, google_click_id, google_gbraid, snapchat_advertiser_cookie_1, snapchat_scid, tiktok_ttp)

traits

Object

Free-form object of traits of the user, like email or name. See the Traits field docs for more details.

Track

Here is an example of a track call:

journify.track("User Registered", {
  plan: "Premium",
  billing: "annual",
  accountType: "Google"
});

As you can notice, the track call takes the following arguments:

Argument

Type

Required

Description

event

String

Yes

Name of the action that a user has performed. See the Event field docs for more details.

properties

Object

Free-form object of properties of the event. See the Properties docs for more details.

traits

Object

Free-form object of traits of the user, like email or name. See the Traits field docs for more details.

Page

Here is an example of page calls:

journify.page("Home page", {
    source: "Google"
});

journify.page({source: "Google"});

journify.page();

As you can notice, the page call takes the following arguments:

Argument

Type

Required

Description

name

String

Name of the page. For example, most sites have a “Signup” page that can be useful to tag.

properties

Object

Free-form object of properties of the page. See the Properties field docs for more details.

Properties

Properties are extra pieces of information that describe the page. They can be anything you want.

Journify adds the following fields automatically:

title: The page's title.
url: The page's canonical URL.
path: The path portion of the page’s URL.
search: the query string portion of the page’s URL.
referrer: The full URL of the page that linked to the current page.
campaign: The UTM campaign tags (id, name, source, medium, term , and content)

Use journify.updateConsent() to set or update the user's consent preferences. Consent is managed globally, you set it once and it is automatically attached to every subsequent event and used to enable or disable client-side destination pixels (Facebook, Google Ads, TikTok, Snapchat, etc.).

journify.updateConsent({
  advertising: "GRANTED",
  analytics: "GRANTED",
  functional: "GRANTED",
  marketing: "DENIED",
  personalization: "GRANTED",
});

Call this whenever the user changes their preferences, for example inside your CMP's consent callback. Destinations whose consent has just been granted are initialized immediately; destinations whose consent has been revoked are removed from the active plugin set.

If you use Google Consent Mode v2, use the fromGoogleConsentV2() helper to convert Google signals to Journify preferences:

import { fromGoogleConsentV2 } from "@journifyio/js-sdk";

// Example: wiring into your CMP's consent update callback
function onConsentUpdated(googleConsent) {
  gtag("consent", "update", googleConsent);
  journify.updateConsent(fromGoogleConsentV2(googleConsent));
}

For full details on consent modes, categories, and how preferences are resolved, see Consent Management.

Source schema

When creating a source, it's required to attach a source schema that outlines which events and properties you are expecting to receive from this source. You can select a schema from our catalog or create a new one from scratch following the JSON Schema Draft-07 spec.

Tips

Troubleshooting

Common errors

So far, our customers haven’t encountered any issues with this source. If anything unexpected comes up, feel free to contact us — we’re ready to assist.

Live debugger

Journify provides complete visibility into what events you are receiving from the source once it's connected with Journify.

PreviousJava SDK NextMySQL

Last updated 23 days ago