Was this helpful?

Creating & incrementing counters (events)

To create a new counter or increment an existing counter, include the counter property in the body of a POST to the /events endpoint. More than one counter can be incremented in the same request.

It may take up to 30 seconds after an event has been posted for the counter to be incremented.

Request syntax

curl -X POST https://api.usergrid.com/<org>/<app>/events -d '{"timestamp":<timestamp>, "counters" : {<counter_name>:<increment_value>}}'

Parameters

Parameter Description
org Organization UUID or organization name
app Application UUID or application name
timestamp

A required UNIX timestamp that specifies the time the counter is being incremented. Specifying a value of 0 will automatically assign the current time.

counter_name

The name of the counter to create or the existing counter to increment.

increment_value

The value to increment the counter by. A negative number can be specified to decrement the value. A value of '0' can be specified to reset the value of the counter.

Example request

The following request will increment the 'button_clicks' counter by one, with a timestamp of the current time.

curl -X POST https://api.usergrid.com/your-org/your-app/events -d '{"timestamp":0, "counters" : {"button_clicks":1}}'

Example response

{
  "action" : "post",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/events",
  "uri" : "https://api.usergrid.com/your-org/your-app/events",
  "entities" : [ {
    "uuid" : "b11217fc-9d3a-1427-b24e-699740088e05",
    "type" : "event",
    "created" : 1401224590293,
    "modified" : 1401224590293,
    "timestamp" : 1401224590293,
    "counters" : {
      "button_clicks" : 1
    },
    "message" : null,
    "metadata" : {
      "path" : "/events/b11217fc-9d3a-1427-b24e-699740088e05"
    }
  } ],
  "timestamp" : 1401224590291,
  "duration" : 30,
  "organization" : "your-org",
  "applicationName" : "your-app"
}
		

SDK method

(ApigeeClientResponse*)createEvent:(NSDictionary*)eventDict
                         timestamp:(NSDate*)timestamp
                  counterIncrement:(ApigeeCounterIncrement*)counterIncrement
		

Parameters

Parameter Description
eventDict An NSDictionary instance specifying any event properties.
timestamp An NSDate instance specifying the timestamp for the event. To automatically set the timestamp to the current time, omit this parameter.
counterIncrements

An ApigeeCounterIncrement instance, specifying the name and value of the counter to be incremented. Alternatively, you can use the following parameter to specify a set of counters to be incremented:

counterIncrements:(NSArray*)counterIncrements

Example request

The following request will increment the 'button_clicks' counter by one, with a timestamp of the current time.

//we recommend you call ApigeeClient from your AppDelegate.
//for more information see the iOS SDK install guide: http://apigee.com/docs/app-services/content/installing-apigee-sdk-ios
//create an instance of AppDelegate
AppDelegate *appDelegate = (AppDelegate *)[ [UIApplication sharedApplication] delegate];

// NSDictionary specifying any properties for the event entity
NSDictionary *eventDict = [[NSDictionary alloc] init];

// the timestamp of when the event is posted.
NSDate *timestamp = [NSDate date];

// the counter name and value to increment
ApigeeCounterIncrement *counter = [[ApigeeCounterIncrement alloc] initWithName: @"button_clicks" incrementValue: 0];

// call createEvent to POST the event and increment the counter
ApigeeClientResponse *response = [appDelegate.dataClient createEvent:eventDict timestamp:timestamp counterIncrement:counter];

@try {
    //success
}
@catch (NSException * e) {
    //fail
}
		

Example response

{
  action = post;
  application = "f34f4222-a166-11e2-a7f7-02e81adcf3d0";
  applicationName = your-app;
  duration = 23;
  entities =     (
          {
      counters =             {
          "button_clicks" = 0;
      };
      created = 1401231997402;
      message = "";
      metadata =             {
          path = "/events/b6140b60-e098-1427-b9e4-7b1d610d1add";
      };
      modified = 1401231997402;
      timestamp = 1401232008454;
      type = event;
      uuid = "b6140b60-e098-1427-b9e4-7b1d610d1add";
    }
  );
  organization = your-org;
  params =     {
  };
  path = "/events";
  timestamp = 1401231997398;
  uri = "https://api.usergrid.com/your-org/your-app/events";
}
		

SDK Method

createEventAsync(final Map eventMap, final CounterIncrement counterIncrement, final ApiResponseCallback callback)

Parameters

Parameter Description
eventMap A Map object containing any properties for the event entity to be created. The timestamp property is required.
counterIncrement A CounterIncrement object that contains the name and value of the counter to be incremented by the event.
callback An ApiResponseCallback object to handle the async response.

Example request

The following request will increment the 'button_clicks' counter by one, with a timestamp of the current time.

// create an instance of the DataClient class
ApigeeClient apigeeClient = new ApigeeClient(ORGNAME,APPNAME,this.getBaseContext());
DataClient client = apigeeClient.getDataClient();

	// create a Map object to represent the event. The 'timestamp' property is required.
Map eventMap = new HashMap();
eventMap.put("timestamp", 0); // a value of 0 sets the timestamp the the current time

// create a CounterIncrement object to specify the name and value of the counter to be incremented
CounterIncrement counter = new CounterIncrement();
counter.setCounterName("button_clicks");
counter.setCounterIncrementValue(1);

// call createEventAsync to initiate the POST request that increments the counter
client.createEventAsync(eventMap, counter, new ApiResponseCallback() {
	@Override
	public void onException(Exception e) { 
		// Error
	}
	
	@Override
	public void onResponse(ApiResponse response) {
	    try { 
	        if (response != null) {
	            // Success - the counter is incremented
	        }
	    } catch (Exception e) { //The API request returned an error
	        	// Fail
	    }
	}
});	
		

Example response

{
  "action" : "post",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/events",
  "uri" : "https://api.usergrid.com/your-org/your-app/events",
  "entities" : [ {
    "uuid" : "b11217fc-9d3a-1427-b24e-699740088e05",
    "type" : "event",
    "created" : 1401224590293,
    "modified" : 1401224590293,
    "timestamp" : 1401224590293,
    "counters" : {
      "button_clicks" : 1
    },
    "message" : null,
    "metadata" : {
      "path" : "/events/b11217fc-9d3a-1427-b24e-699740088e05"
    }
  } ],
  "timestamp" : 1401224590291,
  "duration" : 30,
  "organization" : "your-org",
  "applicationName" : "your-app"
}
		

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

SDK method

Incrementing a counter

Counter.increment(options, callback)

Decrementing a counter

Counter.decrement(options, callback)

Resetting a counter

Counter.reset(options, callback)

Parameters

Parameter Description
options

An options object, specifying the counter name and value to increment. For example:

{
	name: 'button_clicks',
	value: 1
}
							

If no value is specified, the counter will be incremented by 1

callback A callback function to handle the asynchronous response.

Example request

var dataClient = new Apigee.Client({
    orgName:'your-org',
    appName:'your-app',
});

// First we create a Counter object to represent an event entity    
var event_options = {
        client: dataClient, //our Apigee.Client instance
        timestamp: 0 // value of 0 sets the timestamp to the current time 
    };

var event = new Apigee.Counter(event_options, function (error, result) {

    if (error) { 
        // Error creating Counter object
    } else { 
        // Counter object created
    }

});

// Then we POST the event to increment the counter
var counter_options = {
        name: 'button_clicks',
        value: 1
    }

event.increment (counter_options, function (error, result) {

    if (error) { 
        // Error incrementing counter        
    } else { 
        // Success incrementing counter        
    }

});
		

Example response

Usergrid.Response {action: "post", application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0", params: Object, path: "/events", uri: "https://api.usergrid.com/your-org/your-app/events"…}
action: "post"
application: "f34f4222-a166-11e2-a7f7-02e81adcf3d0"
applicationName: "your-app"
duration: 26
entities: Array[1]
	0: Object
	category: "UNKNOWN"
	counters: Object
		button_clicks: 1
	__proto__: Object
	created: 1401227735616
	message: null
	metadata: Object
	modified: 1401227735616
	timestamp: 1401227735616
	type: "event"
	uuid: "f7abe47e-b9d5-1427-894d-b1e8ed6cfe8a"
	__proto__: Object
	length: 1
	__proto__: Array[0]
err: null
logger: Logger
organization: "your-org"
params: Object
path: "/events"
status: 200
statusGroup: 200
success: true
timestamp: 1401227735612
uri: "https://api.usergrid.com/your-org/your-app/events"
__proto__: Object
		

The example assumes use of the Apigee Ruby Gem.

Example request

usergrid_api = 'https://api.usergrid.com/'
organization = 'your-org'
application = 'your-app'

client = Usergrid::Application.new "#{usergrid_api}/#{organization}/#{application}"

begin
	response = client.create_event timestamp: '0', category: 'advertising', counters: { button_clicks: 1 }
	#success
rescue
	#fail
end
		

Example response

{
  "action" : "post",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/events",
  "uri" : "https://api.usergrid.com/your-org/your-app/events",
  "entities" : [ {
    "uuid" : "12a39fd2-2a37-142a-9906-7df9a523aae9",
    "type" : "event",
    "created" : 1401296386848,
    "modified" : 1401296386848,
    "timestamp" : 1401296386848,
    "category" : "advertising",
    "counters" : {
      "button_clicks" : 1
    },
    "message" : null,
    "metadata" : {
      "path" : "/events/12a39fd2-2a37-142a-9906-7df9a523aae9"
    }
  } ],
  "timestamp" : 1401296386844,
  "duration" : 26,
  "organization" : "your-org",
  "applicationName" : "your-app"
}
		

The example assumes use of the Node.js module.

SDK method

Incrementing a counter

Counter.increment(options, callback)

Decrementing a counter

Counter.decrement(options, callback)

Resetting a counter

Counter.reset(options, callback)

Parameters

Parameter Description
options

An options object, specifying the counter name and value to increment. For example:

{
	name: 'button_clicks',
	value: 1
}
							

If no value is specified, the counter will be incremented by 1

callback A callback function to handle the asynchronous response.

Example request

var dataClient = new Usergrid.client({
    orgName:'your-org',
    appName:'your-app',
});

// First we create a Counter object to represent an event entity    
var event_options = {
        client: dataClient,
        timestamp: 0        
    };

var event = new Usergrid.Counter(event_options, function (error, result) {

    if (error) { 
        // Error creating Counter object
    } else { 
        // Counter object created
    }

});

// Then we POST the event to increment the counter
var counter_options = {
        name: 'button_clicks',
        value: 1
    }

event.increment (counter_options, function (error, result) {

    if (error) { 
        // Error incrementing counter        
    } else { 
        // Success incrementing counter           
    }

});
		

Example response

{ action: 'post',
  application: 'f34f4222-a166-11e2-a7f7-02e81adcf3d0',
  params: {},
  path: '/events',
  uri: 'https://api.usergrid.com/your-org/your-app/events',
  entities: 
   [ { uuid: '462599fc-f823-1427-9b82-c76176923f06',
       type: 'event',
       created: 1401234585791,
       modified: 1401234585791,
       timestamp: 1401234585791,
       category: 'UNKNOWN',
       counters: [Object],
       message: null,
       metadata: [Object] } ],
  timestamp: 1401234585787,
  duration: 17,
  organization: 'your-org',
  applicationName: 'your-app' }
		

Decrementing/resetting counters

To decrement a counter, specify a negative number for the counter value in any of the above examples.

To reset a counter, specify a value of 0 for the counter value in any of the above examples.

Note that the Apigee JavaScript SDK also provides dedicated methods for decrementing and resetting counters.

Using counters hierarchically

Counters can be created and incremented hierarchically using dot notation, e.g. button_clicks.homepage.

This can be useful if you want to store, view or increment counter data in a hierarchical way. For example, suppose you want to log errors that your app generates. You can get more detail by creating multiple hoerarchical counters for each module and function within that module. So, by creating this set of counters:

errors
errors.module
errors.module.function

Incrementing any of the counters would simultaneously increment its parent counters. So, for example, incrementing errors.module.function by 1 would increment all three counters by 1. This can be a useful way of easily tracking actions in your app at both a cumulative and granular level.

Help or comments?

  • Something's not working: See Apigee Support
  • Something's wrong with the docs: Click Send Feedback in the lower right.
    (Incorrect? Unclear? Broken link? Typo?)