Error rendering macro 'navitabs' : com.atlassian.renderer.v2.macro.MacroException: The root page with the name 'Analytics SDK (Android)' does not exist in space with key 'DD'!

To view the method signatures, visit this link: http://phunware.github.io/maas-analytics-android-sdk/

To view the method signatures, visit this link: http://phunware.github.io/maas-analytics-ios-sdk/

This document describes the specification for the MaaS Analytics API ("API"). This API allows remote clients to input and report on various pieces of data in the Analytics system.

Security

All calls made must adhere to the guidelines presented in the MaaS REST API Security Protocol document.

Definitions

Term	Definition
Aggregate Event	An aggregate event object contains a collection of event objects. The maximum size of the collection is 100 event objects.
Report	A report object contains data that results from processing events.
Event	An event object contains data to be captured for further processing (either near real-time or scheduled).
Access Key	A unique key that identifies the client making the request. This key is used to get the additional keys used for request signing and encryption.
Signature Key	A unique key that is used to sign requests. The signature is used to both check request authorization as well as data integrity.
Encrypt Key	The key used to encrypt and decrypt data that is exchanged between the client and the server.
MaaS	Multiscreen as a Service.
OpenSSL	A cryptography library used to handle the encryption and decryption of the data. See http://www.openssl.org/ for more details.
JSON	Stands for JavaScript Object Notation and is used for the request and response formats due to its portability and simplicity.
RFC 3339	A date format that "provide[s] an unambiguous and well-defined method of representing dates and times." See http://www.ietf.org/rfc/rfc3339.txt for more details.

ON THIS PAGE

Request / Response Format

JSON is used for the request and response format. JSON is a lightweight and portable format that maintains human-readability.

When making POST or PUT requests, the request parameters MUST be JSON-encoded and placed in the request body. When making GET requests, the request parameters MUST be JSON-encoded, then URI-encoded and placed directly in the query string.

Clients should expect JSON-encoded responses for every request, even those that result in an error.

HTTP Method

Each method defines the HTTP method required depending on what the usage is. For example, if the method were used to simply get data, the HTTP method would be GET. If the method is used to delete data it uses DELETE.

Date / Time Format

The date and time MUST be expressed in RFC 3339 format: YYYY-MM-DDThh:mm:ssZ

All times must be in the UTC time zone and indicated with a "Z". This is done to mitigate issues regarding Daylight Saving Time (DST).
No fractional seconds are allowed.
See section 5.6 of Date and Time on the Internet: Timestamps for more information.

Ellipses ("…"s)

Whenever an ellipsis ("…") appears in the JSON body, treat it as a placeholder for additional instances of the data that immediately precedes it.

GET Methods and Query Strings

The GET methods outlined in this document will use query strings, not JSON bodies, when making a request to a URL. This requires the user to convert JSON into a URL-encoded query string. Here's an example:

{ 
	"tags":  
	{ 
		"any":  
		[ 
			"Zelda", 
			"Link" 
		] 
	} 
}

Minified fragment (using http://bigaqua.org/minify_json.html).

{"tags":{"any":["Zelda","Link"]}}

URL-encoded, minified fragment (using http://www.url-encode-decode.com/):

%7B%3Ftags%3F%3A%7B%3Fany%3F%3A%5B%3FZelda%3F%2C%3FLink%3F%5D%7D%7D

This URL-encoded, minified fragment is the query string. In order to compose a request, a "?" is appended to the end of the request URL, then the URL-encoded, minified fragment is added after that:

http://localhost:8080/v1.0/events?%7B%3Ftags%3F%3A%7B%3Fany%3F%3A%5B%3FZelda%3F%2C%3FLink%3F%5D%7D%7D

ON THIS PAGE

Below are the definitions for the different types of objects used in the Analytics system.

Aggregate Event

An aggregate event object contains a collection of event objects. The maximum size of the collection is 100 event objects.

{
    "schemaVersion": <string>,
    "aggregateEvents": 
	[
        {
            "schemaVersion": <string>,
            "timestamp": <string>,
            "type": <string>,
            "action": <string>,
            "app": 
			{
                "applicationId": <string>
            },
            "alertEnqueued": 
			{
                "alertId": <string>,
                "user": <string>,
                "subscriptions": <string>,
                "broadcast": <Boolean>,
                "whenToSend": <string>,
                "message": <string>,
                "count": <integer>,
                "messagingService": <string>
            },
            "custom": 
			{
            }
        },
        <second event object>,
        ...
    ]
}

Report

A report object contains data that results from processing events. The fields will vary depending on the type of report. Here is a generic example:

{
    "type": <string>,
    "alertId": <string>,
    "units": <string>,
    "data": 
	[
        <object>,
        <object>,
        ...
    ]
}

Event

An event object contains data to be captured for further processing (either near real-time or scheduled).

{
    "schemaVersion": <string>,
    "timestamp": <string>,
    "type": <string>,
    "action": <string>,
    // Not all payloads will require a "sessionId". See Payload Variations by Event for details.
	"sessionId": <string>,
    "app": 
	{
        "applicationId": <string>,
        "ver": <string>
    },
    // Not all payloads will require a "location" object. See Payload Variations by Event for details.
	"location": 
	{
        "lat": <float>,
        "long": <float>,
        "altitude": <integer>,
        "hAccuracy": <integer>,
        "vAccuracy": <integer>
    },
    // Not all payloads will require a "device" object. See Payload Variations by Event for details. 
	"device": 
	{
        "userAgent": <string>,
        "os": <string>,
        // NOTE: For the Alerts Subscribe Device and Alerts Unsubscribe Device actions, only the "id" object is required to compose a valid "device" object.
		"id": 
		{
            "value": <string>,
            "type": <string>,
            "encoding": <string>
        },
        "lang": <string>,
        "timezone": <string>,
        "make": <string>,
        "model": <string>,
        "osv": <string>,
        "osApiLevel": <string>,
        "macAddress": <string>,
        "ipAddress": <string>,
        "carrier": <string>,
        "connection": <string>,
        "SSID": 
		{
            "BSSID": <string>,
            "SSID": <string>,
            "SSIDDATA": <string>
        }
    },
    "custom": 
	{
    },
    
	// Depending on the type and action specified, the payload will also include one of the below objects.
	"alertOpened": 
	{
        "alertId": <string>
    },
    "alertsDisabled": 
	{
        "deviceToken": <string>,
        "tokenType": <string>,
        "isSandbox": <Boolean>
    },
    "alertEnqueued": 
	{
        "alertId": <string>,
        "user": <string>,
        "subscriptions": <array>,
        "broadcast": <Boolean>,
        "whenToSend": <string>,
        "message": <string>,
        "count": <integer>,
        "messagingService": <string>
    },
    "subscribeDevice": 
	{
        "subscriptions": <array>
    },
    "unsubscribeDevice": 
	{
        "subscriptions": <array>
    },
    "moduleRegistration": 
	{
        "modules": <array>
    },
    "applicationEventData": 
	{
        "eventName": <string>,
        "duration": <integer>,
        "namespace": <string>,
        "eventParameters": <array>
    },
    "venue": 
	{
        "venueId": <string>,
        "itemType": <string>,
        "itemId": <integer>
    }
}

ON THIS PAGE

Below are the event payloads in use with our Analytics API.

Below are the methods in use with our Analytics API.

HTTP Status Codes

Below is a detailed outline of the status codes and messages used in the API.

Status Code	Message	Description
200	Success	Used for general success. Used when a POST operation results in the creation of a new resource (such that response should contain URI of newly created resource).
400	Bad Request	Used when one or more parameters are invalid. Used when one or more required parameters are missing. Used when the JSON payload is not valid JSON.
403	Forbidden	Used when the operation fails security checks (e.g. wrong app ID specified as input to retrieve specific data).
404	Not Found	Used when the requested resource does not exist (e.g. app ID).
500	Internal Server Error	Used when the (internal) server is down.

Error Payloads

Each failed response will include a JSON payload that includes the error code number and message:

400

The actual message for this "Bad Request" error will vary depending on whether the error was caused by bad data sent in the request, a validation error when validating the request data or any other generic request error.

{
    "error": 
	{
        "code": 400,
        "message": <error string>
    }
}

403

The actual message for this "Forbidden" error will vary.

{
    "error": 
	{
        "code": 403,
        "message": <error string>
    }
}

404

The actual message for this "Not Found" error will vary depending on what could not be found.

{
    "error": 
	{
        "code": 404,
        "message": <error string>
    }
}

500

{
    "data": 
	{
        "code": 500,
        "message": "An unknown error occurred."
    }
}

ON THIS PAGE

Source Documents - Android API - Analytics

Security

Definitions

Request / Response Format

HTTP Method

Date / Time Format

Ellipses ("…"s)

GET Methods and Query Strings

Aggregate Event

Report

Event

HTTP Status Codes

Error Payloads

400

403

404

500

8 Child Pages