API Documentation > action

Description

Log and query user actions.

Log records, in addition to the traditional fields like referrer and ip address, are composed of a named action and a tag. The action is simply a free-form string. The tag is an object/array with any number of fields of any value including nested objects/arrays. Here is a simplified example of a log record:

{
    action: 'button.click',
    tag: {
        item_id: '123abc',
        network: 'twitter',
        referral: {
            network: 'facebook',
            user_id: 'foo23'
        }
    }
}

When querying log data, it is possible to filter and/or aggregate actions by one or more tag fields, except when querying unique actions. In order to provide reasonable performance when querying unique actions, a specialized index is used. This index does not support aggregation by tag fields and supports filtering only by predefined groups of tag fields known as scopes. For example, <tag.group,tag.network> is a scope. If present in the index, it is possible to get a count of unique actions filtered by tag.group and tag.network. If you wanted to get a unique count of an action filtered by group and not network you would use a different scope, namely <tag.group>.

These are the currently defined scopes:

  • <tag.network> - The social network involved in the action. For example, in the case of a sharelink.click, tag.network is the social network where the share link was posted.
  • <tag.traffic_source> - The auto-generated traffic source based on referrer. It may be one of search, direct, click.st or other.
  • <tag.group> - A user-defined string for a group.
  • <tag.group,tag.traffic_source> - Combination of group and traffic source.
  • <tag.group,tag.network> - Combination of group and network.

List of known actions currently in use:

  • pageview - Click.st script loaded on page.
  • button.load - A share button is drawn.
  • button.click - A share button is clicked. Implies a share but does not guarantee one.
  • email.send - A share email was sent. This is a guaranteed share.
  • sharelink.click - A shared link was clicked.
  • conversion - A user was converted. The exact meaning of a conversion is application dependent.

Methods

action.find()

roles: organization, organization_restricted

Query a view.

Arguments

view: type=string

The name of the view to query.

[ query: type=array, default=NULL ]

Conditions on dimensions of the view.

[ start: type=int, default=NULL ]

Beginning of time range (inclusive)

[ end: type=int, default=NULL ]

End of time range (exclusive)

[ series: type=bool, default=false ]

If true, return series data

[ period: type=string, default='day' ]

If returning series data, aggregate on the given period (month, week day).

action.find_batch()

roles: organization, organization_restricted

Perform a number of queries and return the results.

Arguments

calls: type=array

An array of argument arrays for find()

action.get_external_stats()

roles: organization, organization_restricted

Get stats about social activity outside of click.st

Arguments

[ start: type=int, default=NULL ]

A unix timestamp specifying the beginning of the time window (inclusive).

[ end: type=int, default=NULL ]

A unix timestamp specifying the end of the time window (exclusive).

[ filter: type=array, default=array ( ) ]

A filter object.

action.log()

roles: organization, organization_restricted

Log an action

Arguments

action: type=string

The name of the action being taken.

This should be something short and descriptive and should represent a unique user action.

url: type=string

The URL at which the action is taken.

[ referrer: type=string, default=NULL ]

The URL that linked to the current (action) URL.

[ tag: type=array, default=NULL ]

An object of arbitrary complexity specifying additional information.

For instance, the tag for a button.click action might look like this:

tag: {
    item_id: '123abc',
    network: 'facebook'
}

[ ip: type=string, default=NULL ]

The ip address of the user taking the action.

[ user_agent: type=string, default=NULL ]

The user agent string of the user taking the action.

action methods