Events
Last Updated: 2020-08-01The 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 nooccurredAt
, the server will applycreatedAt
- type - Set by the client, required. The named type of the event. Examples include
pageview
,item-added-to-cart
,purchase
, orclick
- 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 theuserId
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 Profile
s 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 userId
s 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
TODO
Having Problems?
If you are having trouble, visit the list of common issues or open a Github issue to get support.