100% compatible with Segment

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

Topics

1 100% compatible with Segment
2 APIs
3 These are the common fields supported by our APIs
- 3.1 Structure
- 3.2 Context

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

journy.io - Help Center

journy.io Spec Overview