Analytics · Android / iOS Reference

Onesecondbefore's Analytics native mobile libraries for iOS and Android let you collect information about visitors in your apps. It consists of a set of commands (e.g. send or set) and a set of (configuration) options that set certain values or change the library's behaviour.

Commands

They are described in more detail below.

osb.config(...)

Creates an instance of a tracker. When you create a tracker you should also specify configuration parameters like the URL of the tracker and the account ID. An instance of a tracker should be created as part of the start-up code of the mobile app.

Usage

import OSB

let osb = OSB.instance
osb.config(accountId: String, trackerUrl: String)
osb.config(accountId: String, trackerUrl: String, siteId: String)
import com.onesecondbefore.tracker.OSB;

// Add this code to your app's initialization code
OSB osb = OSB.getInstance();
osb.config(Context context, String accountId, String trackerUrl);
osb.config(Context context, String accountId, String trackerUrl, String siteId);

Parameters

parameter nametyperequireddescription
contextContextAndroid onlyContext / Activity.
accountIdstringyesAccount id which specifies where your hits will be stored.
trackerUrlstringyesURL of the tracker used by the app
siteIdstringnoOptional identifier used to group hits together

Examples

// Minimal configuration for account "account". The siteId will be "development"
let osb = OSB.instance
osb.config(accountId: "account", trackerUrl: "https://myconsent.mydomain.com")

// Creates a tracker for "account" with siteId "mysite.app":
let osb = OSB.instance
osb.config(accountId: "account", trackerUrl: "https://myconsent.mydomain.com",
    siteId: "mysite.app")
// Minimal configuration for account "account".
import com.onesecondbefore.tracker.OSB;

// this is Context / Activity
OSB osb = OSB.getInstance();
osb.config(this, "development", "https://myconsent.mydomain.com");

// Creates a tracker with site-id specified:
OSB osb = OSB.getInstance();
osb.config(this, "account", "https://myconsent.mydomain.com", "mysite.app");
[top]

osb.profile(...)

Retrieves the profile of the user in real-time. Contact us to enable the profile service for your account.

Usage

import OSB

let osb = OSB.instance
let profile = osb.profile()
import org.json.JSONObject;
import com.onesecondbefore.tracker.OSB;

// Add this code to your app's initialization code
OSB osb = OSB.getInstance();
JSONObject profile = osb.profile();
[top]

osb.send(...)

Sends an event hit to the analytics server.

Usage

let osb = OSB.instance
osb.send(type: OSBHitType, subtype: String, data: [String: Any])
OSB osb = OSB.getInstance(); 
osb.send(OSB.HitType type, String subtype, Map<String, Object> data);

Parameters

parameter nametyperequireddescription
typeenumyesSpecifies the type to send. The type will be written in column hit_type, except for 'action', where sub_type will be used. See below for the supported types
subtypestringyes if type == "action"You can choose an action from the ga() command queue (detail, add, remove, checkout, checkout_option, purchase, refund or promo_click), or use your own action as long as they only contain letters, numbers and/or underscores. The given subtype will be stored in the hit_type column.
dataMap or DictionarynoContains additional type specific data. Is saved depending on the hit type. Read all about it in the Data Options

Type overview

Below types are defined in the enum OSB.HitType (Android) or OSBHitType (iOS).

iOS typeAndroid typedescription
OSBHitType.aggregateOSB.HitType.AGGREGATEtracks an aggregate event. All hits will be aggregated during sessionization and by pushed to the trash table.
OSBHitType.eventOSB.HitType.EVENTtracks an event. Table column hit_type will contain 'event'.
OSBHitType.idsOSB.HitType.IDStracks identifiers.
OSBHitType.pageviewOSB.HitType.PAGEVIEWtracks a pageview, column hit_type will contain 'pageview'. To be used if your app's navigation structure is similar to the website, e.g. a news app.
OSBHitType.screenviewOSB.HitType.SCREENVIEWtracks a screenview, column hit_type will contain 'screenview'.
OSBHitType.viewable_impressionOSB.HitType.VIEWABLE_IMPRESSIONtracks a viewable_impression, column hit_type will contain 'viewable_impression'.

Examples

let data = [
    "category": "Video",
    "action": "start",
    "label": "Funny cat movie"
]
let osb = OSB.instance
osb.send(type: OSBHitType.event, data: data)

try osb.send(type: OSBHitType.aggregate, scope: "page", name: "scrolldepth", aggregateType:
    OSBAggregateType.max, value: 0.8)

try osb.send(type: OSBHitType.event, category: "Category", action: "Action", label: "Label", value: "1",
    data: [["extra1": "a", "extra2": 3.1415]])

osb.setIds(data: [["key": "a3", "value": "12345"], ["key": "a3-1", "value": "12345-1"]])
try osb.send(type: .pageview)

osb.setConsent(data: ["marketing", "social", "functional", "advertising"]);
osb.set(type: .page, data: [["article": 123]])
try osb.send(type: .pageview, data: [["b": 2]])
try osb.send(type: .pageview)

try osb.send(type: .viewable_impression, data: [["a": 1, "b": 2]])

osb.set(type: .item, data: [
    ["id": "sku123", "name": "Apple iPhone 14 Pro", "category": "mobile", "price": 1234.56,
        "quantity": 1],
    ["id": "sku234", "name": "Samsung Galaxy S22", "category": "mobile", "price": 1034.56,
        "quantity": 1]
])
//- try osb.send(type: .action, actionType: "purchase", data: [
//-     ["id": "abcd1234", "revenue": "2269.12", "tax": "476.52", "shipping": 100,
//-         "affiliation": "partner_funnel"]
//- ])
OSB osb = osb.getInstance();
Map<String, Object> data = new HashMap<>();
data.put("category", "Video");
data.put("action", "start");
data.put("label", "Funny cat movie");
osb.send(OSB.EventType.EVENT, null, data);

// or use
osb.sendEvent("Video", "start", "Funny cat movie");
[top]

osb.sendPageView(...)

Sends a pageview hit to the analytics server. Pageviews are a specific kind of event with a number of fixed parameters.

Parameters

Accepts the data options for page.

Usage

let osb = OSB.instance
osb.sendPageView(url: String)
osb.sendPageView(url: String, title: String)
osb.sendPageView(url: String, title: String, referrer: String)
osb.sendPageView(url: String, title: String, referrer: String, data: [String: Any])
OSB osb = OSB.getInstance();
osb.sendPageView(String url);
osb.sendPageView(String url, String title);
osb.sendPageView(String url, String title, String referrer);
osb.sendPageView(String url, String title, String referrer, Map<String, Object> data);

Examples

Sends a pageview:

let osb = OSB.instance
osb.sendPageView("https://mysite.app/page/subpage", "Page Title")
OSB osb = osb.getInstance();
osb.sendPageView("https://mysite.app/page/subpage", "Page Title");
[top]

osb.sendEvent(...)

Sends an event hit to the analytics server.

Parameters

Accepts the data options for event.

Usage

let osb = OSB.instance
osb.sendEvent(category: String)
osb.sendEvent(category: String, action: String)
osb.sendEvent(category: String, action: String, label: String)
osb.sendEvent(category: String, action: String, label: String, value: String)
osb.sendEvent(category: String, action: String, label: String, value: String, data: data)
osb.sendEvent(category: String, action: String, label: String, value: String, data: data, interaction: Bool)
OSB osb = OSB.getInstance();
osb.sendEvent(category: String)
osb.sendEvent(category: String, action: String);
osb.sendEvent(category: String, action: String, label: String);
osb.sendEvent(category: String, action: String, label: String, value: String);
osb.sendEvent(category: String, action: String, label: String, value: String, data: data);
osb.sendEvent(category: String, action: String, label: String, value: String, data: data, interaction: boolean);

Examples

Sends an event:

let osb = OSB.instance
try osb.sendEvent(category: "Category", action: "Action", label: "Label", value: "1", data: [["extra1": "a", "extra2": 3.1415]])
OSB osb = osb.getInstance();
Map<String, Object> data = new HashMap<>();
data.put("imdb rating", "5"):
osb.sendEvent("Video", "play", "Funny cat movie", 1, data);
[top]

osb.sendScreenView(...)

Sends a screenview hit to the analytics server. Screenviews are a specific kind of event with a number of fixed parameters.

Usage

let osb = OSB.instance
osb.sendScreenView(name: String)
osb.sendScreenView(name: String, data: [String: Any])
OSB osb = OSB.getInstance();
osb.sendScreenView(String name);
osb.sendScreenView(String name, Map<String, Object> data);

Parameters

parameter nametyperequireddescription
screenNamestringyesScreen name.
classNamestringnoClass name.
dataMap or DictionarynoContains additional type specific data. Accepts the data options for screen.

Examples

Sends a screenview:

let osb = OSB.instance
try osb.sendScreenView(screenName: "Homepage", className: "MainController", data: ["a":"1", "b":"2"])
OSB osb = osb.getInstance();
osb.sendScreenView("The screen name with helper", "The class name with helper");
[top]

osb.set(...)

Sets additional properties in the payload. The payload will not be sent after a set command. Only a subsequent 'send' will send the hit.

Usage

let osb = OSB.instance
osb.set(name: String, data: [String: Any])
OSB osb = OSB.getInstance();
osb.set(String name, Map<String, Object> data);

Parameters

nametyperequireddescription
namestringnoName of object used to group additional data under in the JSON payload. See Data Options for more info.
dataMap or DictionaryyesA Map (Android) or Dictionary (iOS) with additional data to store.

Examples

let osb = OSB.instance
osb.set("ids", data: ["username": "john.doe@example.com"])

Map<String, Object> data = new HashMap<>();
data.put("username", "john.doe@example.com");
OSB osb = OSB.getInstance();
osb.set("ids", data);

Map<String, Object> data = new HashMap<>();
data.put("page_id", "123456");
data.put("other_id", "98765");
OSB osb = OSB.getInstance();
osb.set(data);
[top]

Set the consent as returned from the WebView that contains the Consent Management Platform. This allows future events to know the consent that was given by the user.

Parameters

Accepts the data options for consent and described in the data options for consent.

Usage

Examples

[top]

osb.setIds(...)

Set the ids. Use this to store user id's.

Parameters

Accepts the data options for ids and described in the data options for ids.

Usage

let osb = OSB.instance
// Set a single value
osb.setIds(data: [["key": String, "value": String, "label": String, hash: Boolean], ...])

Map<String, Object> ids1 = new HashMap<>();
ids1.put("key", String);
ids1.put("value", String);
ids1.put("label", String);
ids1.put("hash", Boolean);

ArrayList<Map<String, Object>> idsList = new ArrayList<>();
idsList.add(ids1);
...more ids can be added...

osb.setIds(idsList);

Examples

let osb = OSB.instance

osb.setIds(data: [["key": "a3", "value": "12345"], ["key": "a3-1", "value": "12345-1"]])

Map<String, Object> ids1 = new HashMap<>();
ids1.put("key", "a3");
ids1.put("value", "12345");

Map<String, Object> ids2 = new HashMap<>();
ids2.put("key", "b4");
ids2.put("value", "6789");

List<Map<String, Object>> idsList = new ArrayList<>();
idsList.add(ids1);
idsList.add(ids2);

osb.setIds(idsList);
[top]

osb.remove(...)

The opposite of set. Resets all values to null or their default values.

Usage

let osb = OSB.instance
osb.remove(name: String)
OSB osb = OSB.getInstance();
osb.remove(String name);

Parameters

nametyperequireddescription
namestringyesName of object used to group additional data under in the JSON payload. See Data Options for all the possible values.

Examples

let osb = OSB.instance
osb.remove("ids")

OSB osb = OSB.getInstance();
osb.remove("ids");
[top]

Data options

Data options can be set along its corresponding command (event, ids, items or pageview) or set with the set or add commands. With set, no hit is sent to the server, whereas with send a hit is sent to the server.

Data options: action

Contains the options of an action. Actions are typically used to track ecommerce actions like purchase or checkout. It will populate the action object (Snowflake) or struct (BigQuery) in the Analytics hits table.

Supported commands

The following commands support the parameters:

  • set · Sets the action object (Snowflake) or Struct (BigQuery) in the current payload, but doesn't send the information to the server.

Parameters

nametypedefault valuedescription
idstringnullOrder or transaction id.
revenuefloatnull Total revenue amount.
shippingfloatnullShipping amount.
taxfloatnullTax amount.
currency_codestringnullContains the currency code. We recommend using the ISO-4217 ISO codes.
any otherstringnullCustom data key/value pairs (up to 50 per hit). Will be stored in the data array of the Analytics hits table.

Examples

The following example shows the most common use-case of how to set and send an action with an item.

try osb.set(type: .item, data: [["id": "sku123",
                                 "name": "Apple iPhone 14 Pro",
                                 "category": "mobile",
                                 "price": 1234.56,
                                 "quantity": 1
                                ],
                                ["id": "sku234",
                                 "name": "Samsung Galaxy S22",
                                 "category": "mobile",
                                 "price": 1034.56, "quantity": 1
                                ]])

try osb.send(type: .action,
            actionType: "purchase",
            data: [["id": "abcd1234",
                    "revenue": 2269.12,
                    "tax": (2269.12 * 0.21),
                    "shipping": 100,
                    "affiliation": "partner_funnel"]])
Map<String, Object> item1 = new HashMap<>();
item1.put("id", "sku123");
item1.put("name", "Apple iPhone 14 Pro");
item1.put("category", "mobile");
item1.put("price", 1234.56);
item1.put("quantity", 1);

Map<String, Object> item2 = new HashMap<>();
item2.put("id", "sku234");
item2.put("name", "Samsung Galaxy S22");
item2.put("category", "mobile");
item2.put("price", 1034.56);
item2.put("quantity", 1);

List<Map<String, Object>> itemData = new ArrayList<>();
itemData.add(item1);
itemData.add(item2);

osb.set(OSB.SetType.ITEM, itemData);
Map<String, Object> data4 = new HashMap<>();
data4.put("id", "abcd1234");
data4.put("revenue", 2269.12);
data4.put("tax", (2269.12 * 0.21));
data4.put("shipping", 100);
data4.put("affiliation", "partner_funnel"); // Custom data item

try {
    osb.send(OSB.HitType.ACTION, "purchase", data4);
} catch (IllegalArgumentException ex) {
    showHitTypeError();
}
[top]

Contains the consent value.

The following commands support the parameters:

  • set· Sets the consent value in the current payload (and sends it with all the following send commands).
  • setConsent· Sets consent value(s) with the convenience method.

The value can be sent as a string or an array, not as a JavaScript object as with other payload data.

typedefault valuedescription
array or stringnullConsent value like 'all' or ['necessary','advertising'] or a valid TC String (IAB Europe) from us as a provider, like: CPUP3OWPUP3OWFjAOBENChCsAP_-AH_-ABpaxK...
[top]

Data options: event

Contains the options of an event. Will populate the event object (Snowflake) or struct (BigQuery) in the Analytics tables.

Supported commands

The following commands support the parameters:

  • set · Sets the event object (Snowflake) or Struct (BigQuery) in the current record.
  • send 'event'· Sets the event object and sends the information. Will show up in the destination table with hit_type=event.
  • sendEvent· Convenience method of the previous command. Will do a data option and value validation before sending.

Parameters

nametypedefault valuedescription
categorystringnullContains the event category, e.g. 'video'.
actionstringnullContains the event action, e.g. 'play'.
labelstringnullContains the event label, e.g 'funny_cat_12345.mov'.
valuenumbernullContains the event value, e.g. 0.
interactionbooleannull (or true)Contains whether the event should be considered an interaction. Only if true, will the hit be sessionized.
any otherstringnullCustom data key/value pairs (up to 50 per hit). Will be stored in the data array of the Analytics hits table.
[top]

Data options: ids

Contains the options of ids. Will populate the ids array in the Analytics tables.

Supported commands

The following commands support the parameters:

  • set · Sets the ids array in a single statement
  • send 'ids'· Sets the ids array in a single statement and sends the information. Will show up in the destination table with hit_type=ids.
  • sendIds· Convenience method of the previous command. Will do a data option and value validation before sending.

Parameters

nametypedefault valuedescription
keystringnullContains the key of the id, e.g. _ga.
valuestringnullContains the id, e.g. 123456789.987654321.
labelstringnullUse this if you want to use the same key in different situations. E.g. a _ga cookie value for different accounts on the same web page.
hashbooleannullUse this if you want Analytics to hash your value in-memory before storing it in the database, e.g. for email addresses or phone numbers. Hashing is done with SHA256(salt + ':' + value) where salt is account specific and can be retrieved from the Onesecondbefore Console (with proper permissions). So if the salt is OSB and the email address is test@onesecondbefore.com, use this statement in BigQuery to calculate the hash: SELECT TO_HEX(SHA256('OSB:test@onesecondbefore.com')) (which would be 'c2ddd2d48ea0889b95b6e2750624b9690deb4feacdc6ef81195b17138c989496').
[top]

Data options: items

Contains the options of items. Will populate the items array in the Analytics tables.

Supported commands

The following commands support the parameters:

  • set · Sets the items array with a single statement

Parameters

nametypedefault valuedescription
idstringnullProduct id or sku.
namestringnullProduct name.
categorystringnullProduct category.
pricefloatnullProduct price.
quantityfloatnullProduct quantity.
any otherstringnullCustom data key/value pairs (up to 50 per hit). Will be stored in the data array of the Analytics hits.action.items.data table.
[top]

Data options: page

Contains the options of a page. Will populate the page object (Snowflake) or struct (BigQuery) in the Analytics tables.

Supported commands

The following commands support the parameters:

  • set · Sets the page object (Snowflake) or Struct (BigQuery) in the current payload, but doesn't send the information to the server.
  • send 'pageview'· Sets the page object and sends the information. Will show up in the destination table with hit_type=pageview.
  • sendPageView· Convenience method of the previous command. Will do a data option and value validation before sending.

Parameters

nametypedefault valuedescription
titlestringJS: document.titleTitle of the page.
idstringnullUnique id of the page in the Content Management System.
urlstringJS: location.hrefURL of the page, in case you want to override the default. If the value starts with the protocol (e.g. http), it is considered a full URL. If the value starts with a slash (/), everything from the path (including query string and fragment) will be overwritten. If the value starts with a question mark (?), everything after the query string (including the fragment) will be overwritten. If the value starts with a hash (#), everything after the fragment will be overwritten.
referrerstringJS: document.referrerURL of the referrer, in case you want to override the default. If the value starts with the protocol (e.g. http), it is considered a full URL. If the value starts with a slash (/), everything from the path (including query string and fragment) will be overwritten. If the value starts with a question mark (?), everything after the query string (including the fragment) will be overwritten. If the value starts with a hash (#), everything after the fragment will be overwritten.
osc_idstringnullOn-site campaign identifier.
osc_labelstringnullAn extra label in case the on-site campaign identifier alone is not enough.
oss_keywordstringnullOn-site search query / keyword.
oss_categorystringnullOn-site search category.
oss_total_resultsintegernullOn-site search total number of search results.
oss_results_per_pageintegernullOn-site search number of search results per result page.
oss_current_pageintegernullOn-site search result current page number.
any otherstringnullCustom data key/value pairs (up to 50 per hit). Will be stored in the data array of the Analytics hits table.
[top]

Data options: screen

Contains the options of a screen(view). Will populate the event object (Snowflake) or struct (BigQuery) in the Analytics tables.

Supported commands

The following commands support the parameters:

  • set · Sets the screen values in the current payload, but doesn't send the information to the server.
  • send 'screenview'· Sets the screen(view) values and sends the information. Will show up in the destination table with hit_type=screenview.
  • sendPageView· Convenience method of the previous command. Will do a data option and value validation before sending.

Parameters

nametypedefault valuedescription
snstringnullScreen name.
cnstringnullClass name.
datastringnullCustom data key/value pairs (up to 50 per hit). Will be stored in the data array of the Analytics hits table.
[top]