Instrumenting your user journey with the Events API

Events are the backbone of the Resonance ecosystem. They enable us to dynamically enter users into offers and referrals, and to dynamically satisfy offers and referrals. They also provide valuable information about how users move through your app. Let's talk about where and how to start firing events.

Where / when to fire events

To avoid bottlenecks on engineering, it's important to instrument key points in the user journey with events. Typically, those key points include signup and activation. (Activation refers to the moment when a user has truly started to use, or has become able to use, your application in its fullness. This usually occurs at the end of onboarding, depending on how your particular app is set up. For simplicity, you might also think of this as the moment where a visitor or a user becomes a customer).

You might have multiple "activation" moments you're interested in. For instance, a website selling widgets could say a user activates when they buy their first widget. Or maybe it's the moment a user makes an account, or it's the moment they update their payment method. These are all feasibly the point at which a visitor or casual user has become a customer (depending on your monetization model of course).

With multiple activation moments, you can start to optimize your acquisition strategies toward one of these moments over another for CAC (customer acquisition cost) efficiency, or for other reasons. Part of that optimization might include testing offers or referrals that steer users toward a particular activation. To make that happen, you will want to fire an event for each of those activation moments, to quickly and easily pivot your offers and referrals, or to test between activations.

Other moments that are probably event-worthy include reactivation (if a user stops using your app but then comes back; this moment might look different from the original activation), purchases or other transactions, referrals (we can collect this data automatically for you if you're also using our Referrals API!) or other points of engagement that you deem are crucial to your application.

How to fire events

Sending events is easy with the Events API. Whether you're on the Offers API plan, the Referrals API plan, or you've got both, the Events API is available to you. Check out the API docs for specifics!

In short, you'll need to:

• give your event a name (we recommend the Object Action naming scheme, which is precise but also human-readable; e.g. Widget Purchased, or Account Created)
• tell us which user took the action that created the event (you do this by passing your user's id in the call to the Events API)
• Pass along any additional metadata you'd like as key/value pairs
• You can also optionally provide an event timestamp, in case the event didn't take place at the same time that you're making the call to the API

Once you've instrumented your application to fire these events, you should see them show up in the Resonance console ready for use. (You can also enter the event names manually in the console before they've been fired—just be sure the name matches what will be coming into the Events API!) You can then create conditions with them, and use those conditions to start entering users into offers, or to determine when an offer or referral has been satisfied and the user has earned the reward.