journy.io Spec Overview

These specs are 100% compatible with http://segment.com specs.


The journy.io specification offers clear guidelines for capturing meaningful data in a consistent format across all of journy.io 's libraries and APIs. When you implement journy.io following these predefined formats, it becomes effortless to seamlessly transfer your data to downstream tools. It's important to note that these specifications are fully compatible with Segment's specifications.

The journy.io specification defines the semantic structure for customer data collected by journy.io across all its libraries and APIs. Within this specification, there are four distinct API calls, each representing a unique category of semantic information about a customer, which includes both user and account details. Importantly, all of these API calls share common fields that provide a standardized foundation for your data.

APIs

  • Identify: who is the customer?

  • Group: what account, company or organization are they part of?

  • Track: what are they doing?

  • Page: what web or app page/screen are they on?

These are the common fields supported by our APIs

Structure

Every API call has the same core structure and fields. These fields describe user identity, timestamping, and mechanical aides like API version.

Here’s an example of these common fields in raw JSON:

{ "anonymousId": "507f191e810c19729de860ea", "userId": "97980cfea0067", "context": { "active": true, "app": { "name": "InitechGlobal", "version": "545", "build": "3.0.1.545", "namespace": "production.journy" }, "campaign": { "name": "TPS Innovation Newsletter", "source": "Newsletter", "medium": "email", "term": "tps reports", "content": "image link" }, "device": { "id": "B5372DB0-C21E-11E4-8DFC-AA07A5B093DB", "advertisingId": "7A3CBEA0-BDF5-11E4-8DFC-AA07A5B093DB", "adTrackingEnabled": true, "manufacturer": "Apple", "model": "iPhone7,2", "name": "maguro", "type": "ios", "token": "ff15bc0c20c4aa6cd50854ff165fd265c838e5405bfeb9571066395b8c9da449" }, "ip": "8.8.8.8", "library": { "name": "analytics.js", "version": "2.11.1" }, "locale": "en-US", "network": { "bluetooth": false, "carrier": "T-Mobile US", "cellular": true, "wifi": false }, "os": { "name": "iPhone OS", "version": "8.1.3" }, "page": { "path": "/academy/", "referrer": "", "search": "", "title": "Analytics Academy", "url": "https://journy.io/academy/" }, "referrer": { "id": "ABCD582CDEFFFF01919", "type": "dataxu" }, "screen": { "width": 320, "height": 568, "density": 2 }, "groupId": "12345", "timezone": "Europe/Amsterdam", "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/113.0.0.0 Safari/537.36", "userAgentData": { "brands": [ { "brand": "Google Chrome", "version": "113" }, { "brand": "Chromium", "version": "113" }, { "brand": "Not-A.Brand", "version": "24" } ], "mobile": false, "platform": "macOS" } }, "integrations": { "All": true, "Mixpanel": false, "Salesforce": false }, "event": "Report Submitted", "messageId": "022bb90c-bbac-11e4-8dfc-aa07a5b093db", "receivedAt": "2015-12-10T04:08:31.909Z", "sentAt": "2015-12-10T04:08:31.581Z", "timestamp": "2015-12-10T04:08:31.905Z", "type": "track", "version": 2 }

In more detail these common fields for every API call are:

FIELD

REQUIRED?

TYPE

DESCRIPTION

anonymousId

required; optional if userID is set instead

String

A pseudo-unique substitute for a User ID, for cases when you don’t have an absolutely unique identifier. A userId or an anonymousId is required.

context

optional

Object

Dictionary of extra information that provides useful context about a message, but is not directly related to the API call like ip address or locale

integrations

optional

Object

Dictionary of destinations to either enable or disable.

messageId

implicit

String

Automatically collected by Segment, a unique identifier for each message that lets you find an individual message across the API.

receivedAt

implicit

Date

Automatically set by Segment, the timestamp of when a message is received by Segment It is an ISO-8601 date string.

sentAt

optional

Date

Timestamp of when a message is sent to Segment, used for clock skew correction It is set automatically by the Segment tracking libraries. It is an ISO-8601 date string.

timestamp

optional

Date

Timestamp when the message itself took place, defaulted to the current time by the Segment Tracking API, as a ISO-8601 format date string. If the event just happened, leave it out and we’ll use the server’s time. If you’re importing data from the past, make sure you to provide a timestamp.

type

implicit

String

Type of message, corresponding to the API method: 'identify', 'group', 'track', and 'page'.

userId

required; optional if anonymousID is set instead

String

Unique identifier for the user in your database. A userId or an anonymousId is required.

version

implicit

Number

Version of the Tracking API that received the message, automatically set by journy.io.

Beyond this common structure, each API call adds a few specialized top-level fields.

Context

Context is a dictionary of extra information that provides useful context about a datapoint, for example the user’s ip address or locale. You should only use Context fields for their intended meaning.

FIELD

TYPE

DESCRIPTION

active

Boolean

Whether a user is active.

This is usually used to flag an .identify() call to just update the traits but not “last seen.”

app

Object

dictionary of information about the current application, containing name, version, and build.

This is collected automatically from the mobile libraries when possible.

campaign

Object

Dictionary of information about the campaign that resulted in the API call, containing name, source, medium, term, content, and any other custom UTM parameter.

This maps directly to the common UTM campaign parameters.

device

Object

Dictionary of information about the device, containing id, advertisingId, manufacturer, model, name, type, and version.

ip

String

Current user’s IP address.

library

Object

Dictionary of information about the library making the requests to the API, containing name and version.

locale

String

Locale string for the current user, for example en-US.

network

Object

Dictionary of information about the current network connection, containing bluetooth, carrier, cellular, and wifi. If the context.network.cellular and context.network.wifi fields are empty, then the user is offline.

os

Object

Dictionary of information about the operating system, containing name and version.

page

Object

Dictionary of information about the current page in the browser, containing path, referrer, search, title and url. This is automatically collected by Analytics.js.

referrer

Object

Dictionary of information about the way the user was referred to the website or app, containing type, name, url, and link.

screen

Object

Dictionary of information about the device’s screen, containing density, height, and width.

timezone

String

Timezones are sent as tzdata strings to add user timezone information which might be stripped from the timestamp, for example America/New_York.

groupId

String

Group / Account ID.

This is useful in B2B use cases where you need to attribute your non-group calls to a company or account. It is relied on by several Customer Success and CRM tools.

traits

Object

Dictionary of traits of the current user.

This is useful in cases where you need to track an event, but also associate information from a previous identify call. You should fill this object the same way you would fill traits in an identify call.

userAgent

String

User agent of the device making the request.

userAgentData

Object

The user agent data of the device making the request. This always contains brands, mobile, platform, and may contain bitness, model, platformVersion,uaFullVersion, fullVersionList, wow64, if requested and available.

This populates if the Client Hints API is available on the browser.

This may contain more information than is available in the userAgent in some cases.

channel

String

where the request originated from: server, browser or mobile


Tip: Need help integrating journy.io to your web-site and/or App?

Reach out to our support team

https://releasemanagement.atlassian.net/servicedesk/customer/portal/14

or book time to make it together