Events

Last Updated: 8/1/2020

The Grouparoo Event System is modeled to be compatible with a number of existing event & analytic systems.

Schema

The 3 models used for the Grouparoo Event System are: events, eventData and apiKeys.

`events` table

This is the primary event table logging a row per event.

guid - The primary Key for this event. Generated by the Grouparoo server. Should /not/ be auto-incremented but others unique (we use UUIDv4) + a evt_ prefix.
producerGuid - “foreign key” for apiKeys. Identifies the API client which created the event, ie: “web API client” vs “iPhone API client”. Set by the grouparoo server.
ipAddress - IP address the event was received from. Set by the grouparoo server.
profileGuid - “foreign key” for profiles. Set by the grouparoo server.
createdAt - The time the Grouparoo Server received the event. Set by the grouparoo server.
updatedAt - The time the Grouparoo Server last modified the event. Set by the grouparoo server.
occurredAt - Set by the client, optional. This likely differs from createdAt as it should store the local time of the event. Event’s may be batched when sent from the client, so we cannot rely on the time server received the event to be the time the event occurred. If there is no occurredAt, the server will apply createdAt
type - Set by the client, required. The named type of the event. Examples include pageview, item-added-to-cart, purchase, or click
userId - Set by the client, optional. If the client knows the primary identifying profile property of the current user, it should be sent. This is /your/ notion of userId. This property takes precedence over anonymousId when present.
anonymousId - Set by the client, required (unless userId is present). If the userId is not known (the user is not yet logged in), a unique ID should be generated by the client. These can be device GUIDs in the case of mobile phones, or just another UUID.

`eventData` table

This is a “has-many” data table logging the data properties of each event. Each event can have 0 or many rows in this table.

guid - Set by the Grouparoo server. The primary Key for this portion of an event’s data. Generated by the Grouparoo server. Should /not/ be auto-incremented but others unique (we use UUIDv4) + a edt_ prefix.
eventGuid - Set by the Grouparoo server. “foreign key” for events table.
key- Set by the client, required. The named key of this portion of an event’s data.
value- Set by the client, required. The value of this portion of an event’s data. All data is stored as strings.

`apiKeys` table

The apiKeys table is stored within Grouparoo’s database. Events must be created with an an apiKey which is authorized to create events.

Workflow

Create an apiKey (_key in our example) which is authorized to create events. We will give it the name “Web API”.
A Client clicks on a Google add for our website and lands on our homepage.
Since we know nothing about this user, we’ll create an anonymousId=person_1 and send an event about the page view:

Grouparoo.init({
  apiKey: "_key",
  endpoint: "https://your-grouparoo-instance.company.com", // likely pre-set by the client library
});

Grouparoo.track({
  anonymousId: "person_1",
  occurredAt: new Date(), // likley a default in the Client Library
  type: "pageview",
  data: {
    path: "/",
    utm_source: "google",
    utm_medium: "cpc",
    utm_campaign: "my-ad-campaign",
    // ...
  },
});

Grouparoo will create a new Profile to track all the activity we can for “person_1”, and attempt to decorate their profile with any additional information we can load from your Profile Property Rules.

Eventually, after visiting a few more pages, the user will sign in, and we’ll know their userId

Grouparoo.track({
  anonymousId: "person_1",
  userId: 123,
  occurredAt: new Date(),
  type: "sign-in",
  data: {
    via: "google-sign-in",
    // ...
  },
});

From this point forward, we will send send anonymousId and userId indicating we know how to identify this user. On the backend, Grouparoo will now be able to check if user 123 already has a Profile, and merge it with the profile we created for “person_1”. In this way, we will have a combined history for all the sessions of this user. If the same user signs in via another client / browser / phone, we will continue to create temporary profiles with an anonymousId, and eventually merge the profiles (and events!) once we have enough data. Both IDs are needed to help us handle race-conditions with multiple sessions for the same user.

Creating events outside of Grouparoo

Grouparoo will not only process events created though our APIs, but will also periodically scan the events table for new events that have been added by an external system. This is a helpful if you want to write events directly from your backend applications. Grouparoo will look for events lacking a profileGuid and associate the events, making new Profiles as needed, finally writing events.profileGuid.

By default, Grouparoo will check for new, un processed events each minute.

Apps & Sources

Grouparoo comes with a built-in app to use with events. We ask that you provide the Profile Property Rule that matches userIds sent from events so we can identify your users.

Once you have events flowing into Grouparoo, you can create Sources against an event type. You can look for counts, sums, diffs, latest values, etc between events to create Profile Properties to use within the rest of Grouparoo.

API Endpoints

TODO

Client Libraries