Action Logging

Actions are logged to Nitro when an activity is performed by a user. POST /users/{userId}/actions and POST /groups/{groupId}/actions are the primary API methods used to log user and group actions. Some actions are automatically logged by Nitro for certain activities. See Nitro Metadata for Nitro defined actions and metadata.

A user is "created" in Nitro the first time an action with that user ID is logged. Users and groups cannot log an action until the action exists in Nitro Studio. Data sent to Nitro must be UTF-8 encoded. Actions are logged when data is sent via:

API call – logging is real-time as the user performs the action
Batch load – the administrator logs the action via data import or by applying the action to a user/group ID

When logging actions, you may want to consider how often a user can do that action in the source system. Some actions, such as logging in, should be limited to avoid gaming the system. You can do this by rate limiting the action or by rate limiting the mission(s) which uses the action. For example, you have a LOGIN action used by the "Login Every Day" mission which awards the user 5 points.

When you rate limit the action to 1 per day, only one action is logged in Nitro in a 24-hour period. The user will be awarded 1 mission and 5 points the first time they log in within a 24-hour period. Subsequent logins within 24 hours will not be logged or awarded.
When you set a daily achievement limit on the mission to 1 per day, every time the user logs in the action is logged in Nitro. However, the user only gets awarded 1 mission and 5 points the first time they log in within a 24-hour period. Subsequent logins within 24 hours will be logged but not awarded for that mission.

Metadata

Metadata is used to add specificity to an action. Using metadata, you can use the same action to complete different tasks of the same type. See more here

Values

Values are used for actions that have numeric goals associated with them such as a dollar amount or a score. For example, you may be tracking course completions and awarding users when they score 80 or above on a course. Values are ignored unless a mission or leaderboard is configured to look for them.

Leaderboards

Although leaderboards allow you to select a leaderboard timezone, you may need to consider backdated actions to ensure actions log on the desired day. This may be the case if you're logging actions via batch load and you have users logging actions in multiple timezones or your leaderboard resets daily/monthly/quarterly/annually.

Throttling

Best Practices Due to data volume, logging actions too quickly for the same user may result in dropped events. Minimizing and/or throttling action logging helps prevent this.

Nitro's policy enforces a rate limit of 250 requests per second (RPS) on all Production sites. This can be adjusted as needed based on an individual customer's contract. The 250 RPS limit is set on all APIs for performance management across programs.

Bunchball recommends implementing API throttling and retry logic to receive the following benefits:

Throttling ensures that you're in compliance for contracted API requests per second (RPS).
Throttling ensures that spikes in volume are managed appropriately from a systems architecture perspective.
Retry logic ensures that action events get processed in the event of a planned or unplanned outage.

Throttling in the form of API RPS should be configurable within the application or system sending action events. For example, 25 API RPS. The application sending action events would not exceed this amount at any one time.

When sending actions via API, Bunchball recommends throttling at 200ms between calls. Calls that update groups should be throttled at 300ms. Both recommendations are conservative, but will ensure a unique timestamp. Adjust as needed for your environment.

Retry logic can be hard coded. Example retry logic is as follows:

Send initial action, and in the event of a failure
Retry 1-30 seconds later
Retry 2-5 minutes later
Retry 3-1 hour later
Retry 4-16 hours later