journy.io Spec Overview
100% compatible with Segment
These specs are 100% compatible with http://segment.com specs.
Topics
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 |
| required; optional if | String | A pseudo-unique substitute for a User ID, for cases when you don’t have an absolutely unique identifier. A |
| optional | Object | Dictionary of extra information that provides useful context about a message, but is not directly related to the API call like |
| optional | Object | Dictionary of destinations to either enable or disable. |
| implicit | String | Automatically collected by Segment, a unique identifier for each message that lets you find an individual message across the API. |
| implicit | Date | Automatically set by Segment, the timestamp of when a message is received by Segment It is an ISO-8601 date string. |
| 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. |
| 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 |
| implicit | String | Type of message, corresponding to the API method: |
| required; optional if | String | Unique identifier for the user in your database. A |
| 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 |
| Boolean | Whether a user is active. |
| Object | dictionary of information about the current application, containing |
| Object | Dictionary of information about the campaign that resulted in the API call, containing |
| Object | Dictionary of information about the device, containing |
| String | Current user’s IP address. |
| Object | Dictionary of information about the library making the requests to the API, containing |
| String | Locale string for the current user, for example |
| Object | Dictionary of information about the current network connection, containing |
| Object | Dictionary of information about the operating system, containing |
| Object | Dictionary of information about the current page in the browser, containing |
| Object | Dictionary of information about the way the user was referred to the website or app, containing |
| Object | Dictionary of information about the device’s screen, containing |
| String | Timezones are sent as tzdata strings to add user timezone information which might be stripped from the timestamp, for example |
| String | Group / Account ID. |
| Object | Dictionary of |
| String | User agent of the device making the request. |
| Object | The user agent data of the device making the request. This always contains |
| String | where the request originated from: server, browser or mobile |