Event Logging

External events can be logged into the BI tool for analytics using the logEvent facility available in the iOS and Android SDKs. These events will merge with the internal Events already being generated by the platform. Once events are logged they can be used in an analytics Dashboard to create queries, joins and Aggregations.

Events can also be logged from any external application that does not use the mobile SDK. To do so the developer must use the Event Logging endpoint available in the Messangi REST API. This endpoint requires parameters to conform to the predefined Events Data Structure used by the platform, and will use several fallback mechanisms to obtain the value corresponding to some fields if they are not present, or they include incomplete information. For example, if the event location is not provided via the endpoint parameters then the HTPP request headers are examined to check for any proxy information; if the request was not proxied then the caller IP address is used to obtain the GeoIP location, but if it was proxied then the originator IP address is extracted from the request HTTP headers before doing the GeoIP identification, effectively using the actual event generator IP address instead of any proxies in between.

Most fields are stored as is on the analytics database, but some are analyzed before ingestion. Additionally some fields will be duplicated in two versions: analyzed and non-analyzed. This allows performing both tokenized and full text search and aggregations. All the endpoint parameters must be passed as GET query string parameters.

The Event Logging endpoint is:

https://api.messangi.com/events/

The accepted parameters are (bold fields are mandatory):

Field Description
deviceid The event generator Device ID. If no Device ID is available then any ID that relates to the recipient can be used
client The Messangi Client ID
app The name of the application that generated the event
platform The platform on which the event was generated. The Messangi SDK uses either Android or iOS, but the web based applications like Scratchcards use the User Agent. This is a free text field, but values must be consistent in order to be used for aggregations
eventtype The type of event. This value is application dependant. For example, Scratchcards generate OPEN, SCRATCHED, CLICKED or TIMEOUT events when the Scratchcard link is opened, the card is scratched, the final link is clicked or the user does nothing with the card respectively. But SDK based events may have different Event Types. Please see Events for more information. This is a free text field.
campaignname The name of the Campaign that triggered this event. Used for aggregation of events in different apps or channels
mobile The mobile number that generated the event. This field may actually contain the recipient's email address and will be renamed to recipient in future releases
address The IP address of the event generator. If not provided then the X-Forwarded-For HTTP header is used. If the X-Forwarded-For HTTP header is not present then the actual IP address used to make the call is used.
version The version of the application that generated the event
extrainfo Any external information (like external IDs used for tracking, or full text information on the event itself) that needs to be associated with the event.
latitude The event generator's latitude. If not provided then extracted from the GeoIP information for the address field after the fallback identification process
longitude The event generator's longitude. If not provided then extracted from the GeoIP information for the address field after the fallback identification process

Example Call

When a Scratchcard link is clicked (on an SMS, Push or Email message) an OPEN event is logged for the Scratchcard application. The campaign_name field will include the Scratchcard name and the platform field will include the user-agent string. This call has this form: 

https://api.messangi.com/events/?deviceid=c3912a90-a&mobile=%2B15555555555&address=162.213.96.149&client=p36madTStSTTooeyIhub&app=scratchcard&version=NONE&eventtype=OPEN&extrainfo=Demo+Card&platform=Mozilla%2F5.0+%28Macintosh%3B+Intel+Mac+OS+X+10_11_4%29+AppleWebKit%2F537.36+%28KHTML%2C+like+Gecko%29+Chrome%2F50.0.2661.102+Safari%2F537.36


Please note that no location information is being sent so the GeoIP fallback mechanism is going to be used. This event will be stored using the following JSON: 

{
  "_index": "stg_05_2016",
  "_type": "ogangi_ev_event",
  "_id": "AVTFdF7AebwX-eI4XAxr",
  "_score": null,
  "_source": {
    "client_date": "2016-05-18T19:55:41.634Z",
    "utc_when": "2016-05-18T19:55:41.634Z",
    "client_id": "p36madTStSTTooeyIhub",
    "client_name": "Ogangi",
    "type": "event",
    "campaign_name": "Demo Card",
    "device_id": "c3912a90-a",
    "origin": "+15555555555",
    "event_type": "OPEN",
    "app": "scratchcard",
    "platform": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_11_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/50.0.2661.102",
    "extra_info": "Demo Card",
    "version": "NONE",
    "address": "162.213.96.149",
    "country": "null",
    "location": "37.3762,-122.1826"
  },
  "fields": {
    "utc_when": [
      1463601341634
    ],
    "client_date": [
      1463601341634
    ]
  },
  "sort": [
    1463601341634
  ]
}


The dashboard will display this event in the following way:



Events are not inserted in real time in the BI platform. The backend platform may wait up to a minute before inserting a batch of pending events, so they won't be available immediately in the dashboards.