Was this helpful?

See all application entities

Events are typically used for event logging in your application. For example, they could be used to log error messages that a system administrator might review at a later time. The event mechanism is optimized to handle large numbers of events, so it is an ideal mechanism for logging in your application.

You can link events to specific users, groups, or custom-defined categories. When created with these links, events offer a powerful tool for running highly targeted, custom reports.

Events are also the primary way to store custom counter data for analytics. See Counters (below) for further details.

Note: Although not shown in the API examples below, you need to provide a valid access token with each API call. See Authenticating users and application clients for details.

Using the API Services BaaS, you can create an event.

Creating a new event

Use the POST method to create a new event in the events collection.

Request URI

POST /{org_id}/{app_id}/events {request body}

Parameters

Parameter Description
arg uuid|string org_id Organization UUID or organization name
arg uuid|string app_id Application UUID or application name
request body

One or more sets of event properties. You must provide a timestamp property, but if you set it to 0 it is assigned by the system.

{
  "timestamp":0,
  "category" : "advertising",
  "counters" : {
    "ad_clicks" : 5
  }
}

Example - Request

curl -X POST "https://api.usergrid.com/my-org/my-app/events" -d '{"timestamp":0, "category" : "advertising", "counters" : {"ad_clicks" : 5}}'

The example assumes use of the JavaScript (HTML5) SDK.

var options = {
    method:'POST',
    endpoint:'events',
    body:{timestamp:0, category:'advertising', counters:{ad_clicks : 5}}
};
client.request(options, function (err, data) {
    if (err) {
        //error
    } else {
        //success - data will contain raw results from API call
    }
});

The example assumes use of the Ruby SDK.

app = Usergrid::Application.new 'https://api.usergrid.com/my-org/my-app/'
result = app.create_event timestamp: '0', category: 'advertising', counters: { ad_clicks: 5 }
mynewevent = result.entity   

The example assumes use of the Node.js module.

var options = {
    method:'POST',
    endpoint:'events',
    body:{timestamp:0, category:'advertising', counters:{ad_clicks : 5}}
};
client.request(options, function (err, data) {
    if (err) {
        //error
    } else {
        //success - data will contain raw results from API call
    }
});

Example - Response

{
      "action": "post",
      "application": "7fb8d891-477d-11e1-b2bd-22000a1c4e22",
      "params": {},
      "path": "/events",
      "uri": "https://api.usergrid.com/22000a1c4e22-7fb8d891-477d-11e1-b2bd/7fb8d891-477d-11e1-b2bd-22000a1c4e22/events",
      "entities": [
        {
          "uuid": "ce07ea3c-68b5-11e1-a586-9227e40e3559",
          "type": "event",
          "created": 1331166585282,
          "modified": 1331166585282,
          "counters": {
            "ad_clicks": 5
          },
          "metadata": {
            "path": "/events/ce07ea3c-68b5-11e1-a586-9227e40e3559"
          },
          "timestamp": 1331166585282
        }
      ],
      "timestamp": 1331166585018,
      "duration": 919,
      "organization": "my-org",
      "applicationName": "my-app"
}

Categorizing events

As mentioned previously, you can link an event to a user or a group. This enables you to categorize and qualify event data for use in tracking and analysis. For example, linking events to users and groups, enables you to track how often people use a feature. Not only can you determine the total number of users that used the feature, but also which groups contain users that made the most use of the feature. Or, you could provide a location with the event, so you could see how often a feature was used by people in San Francisco versus Los Angeles.

Counters

User-defined counters are used in conjunction with events to keep statistics on many aspects of an application. User-defined counters are JSON objects that are added to events when they are posted. The act of posting an event increments the counter. Once created, user-defined counters can be used to get reports.

Note: It may take up to 30 seconds for a counter to be updated.

User-Defined Counters

With API Services, you can define your own counters. Some of the things that you might track with a user-defined counter are:

  • How many times people click on the help button in your application.
  • How many times your game is played each day.
  • How many times your banner ads are clicked each day.

You can choose any name for a user-defined counter. For example, the counter for the help button might be named “help_button” or “help_button_clicks”.

To create a user-defined counter, you post to the events collection and specify the name and increment value of the counter in the request body. The increment value is the value that the counter is incremented by for each tracked event. An increment value of 1, means that the counter is increment by 1 for each tracked event. You could also specify a higher increment value, such as 15, which would increment the value by that number, or a negative number, which would decrement the value.  You can also reset the value of the counter, by specifying an increment value of 0.

When a counter is incremented by an event, there will be a 20-30 second delay between when the event is posted and when the counter is incremented. 

As an example, here's how to create a user-defined counter named “button_clicks” with an increment value of 1:

POST https://api.usergrid.com/my-org/my-app/events {"counters" : {"button_clicks" : 1},"timestamp" : "0"}

The response body would look something like this:

{
   "action": "post",
   "path": "/events",
   "uri": "http://api.usergrid.com/438a1ca1-cf9b-11e0-bcc1-12313f0204bb/events",
   "entities": [
       {
           "uuid": "39d41c46-d8e4-11e0-bcc1-12313f0204bb",
           "type": "event",
           "timestamp": 1315353555546016,
           "category":"advertising",
           "counters": {
               "button_clicks": 1
           },
           "created": 1315353555546016,
           "modified": 1315353555546016,
           "metadata": {
           "path": "/events/39d41c46-d8e4-11e0-bcc1-12313f0204bb"
           }
       }
   ],
   "timestamp": 1315353555537,
   "duration": 110,
   "organization": "my-org",
   "applicationName": "my-app"
}

Counter hierarchy

Counters are hierarchical in their structure and in the way they are incremented. Each level of the hierarchy is separated by the dot “.” operator. The hierarchical structure can be useful if you want to store or view statistics in a hierarchical way. For example, suppose you want to log errors that your app generates. One way to do this, is to fire an event every time an error occurs, by creating a counter called “errors”. However, you can get more detail by adding additional parameters to the counter. Imagine that you want to track errors in a specific module and function within that module, say module_1, function_1, you could use a counter like this:

errors.module_1.function_1

And then for a different function in the same module:

errors.module_1.function_2

And then for a different function in a different module:

errors.module_2.function_3

If each of the preceding examples were called once, the resulting values would be:

errors = 3
errors.module_1 = 2
errors.module_1.function_1 = 1
errors.module_1.function_2 = 1
errors.module_2 = 1
errors.module_2.function_3 = 1

This tells you that there were 3 errors in the application, with 2 of those errors in module_1. You can then drill down further to see errors in specific functions.

Using counters in time series queries

Knowing the value of a counter is useful. However, you often need to know how the value varies over time. Fortunately, the API provides a method for you to view this data over any time interval or level of granularity.

For example, let’s say you’re incrementing a counter every time someone launches your application. You might be interested in which days of the week the application sees the most usage. Using the API, you can examine the counter over a set of weeks, with the data split into daily intervals. Using this information, you can see which are your peak days of usage. You can also view usage across a single day, so you can see if your application is used more in the mornings or the evenings. For business reporting, you may be more interested in monthly reporting.

Note that the system is able to provide you with the report data as you need it. The data is maintained in real-time so it can be viewed instantly.

Retrieving counter data

To retrieve counter data, you issue a GET request to the /counters endpoint. This is a special, built-in collection that gives you access to all the counters currently in the system. The API also provides a number of parameters that you can use to search for counter data, as follows:

Parameter Type Description
start_time An Epoch(Unix) timestamp in milliseconds The beginning of the time period to search
end_time An Epoch(Unix) timestamp in milliseconds The end of the time period to search
counter string The name of a specific counter to search. You can specify more than one counter in a query (for example, counter=counter1&counter=counter2...)
resolution string The interval at which counters are displayed. For example, if the interval is day, and the start time and end time values span 4 days, you will get aggregate counts for each of the 4 days. Possible values are all, minute, five_minutes, half_hour, hour, six_day, day, week, and month.

For example, to retrieve a time range of values, with a granularity of "day", for a counter called "button_clicks", the GET request would look like this:

GET /my-org/my-app/counters?start_time=1315119600000&end_time=1315724400000&resolution=day&counter=button_clicks

The response body would look something like this:

{
 action: "get",
    uri: "http://api.usergrid.com/438a1ca1-cf9b-11e0-bcc1-12313f0204bb/counters",
    timestamp: 1315354369272,
    duration: 28,
    counters: [
        {
            name: "button_clicks",
            values: [
                {
                    value: 2
                    timestamp: 1315180800000
                },
                {
                    value: 1
                    timestamp: 1315267200000
                },
                {
                    value: 1
                    timestamp: 1315353600000
                }
            ]
        }
    ]
}

Comments

If I have registered many event app_invoke.user.1, app_invoke.user.2, ... ... app_invoke.user.245
how I retreive individual users invoke app daily count ?
I want to know my users app invoke daily count.

Hi Taeho

You will do a time series GET on the counters endpoint in this format:

GET /<your-org>/<your-app>/counters?start_time=<UTC timestamp>&end_time=<UTC timestamp>&resolution=day&counter=<counter name>

Add new comment

Provide your email address if you wish to be contacted offline about your comment.
We will not display your email address as part of your comment.

We'd love your feedback and perspective! Please be as specific as possible.
Type the characters you see in this picture. (verify using audio)

Type the characters you see in the picture above; if you can't read them, submit the form and a new image will be generated. Not case sensitive.