=== Event Logging ===

External events can be logged into the BI tool for analytics using the logEvent facility available in the [[https://www.messangi.com/documentation/doku.php?id=messangisdk|iOS]] and [[https://www.messangi.com/documentation/doku.php?id=androidsdk|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 [[Aggregation]]s.

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:

<code>
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
</code>
\\ 

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:
\\ \\ 

<code>
{
  "_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
  ]
}
</code>
\\ 
The dashboard will display this event in the following way:
\\ \\ 

{{ ::dashboard-event1.png?800 }}
\\ \\ 

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.