Skip to main content

Custom Events

Understanding the performance of your playables beyond the ad network metrics is key to optimising your creative.

Unity Playworks Plugin captures a number of standard events automatically for every playable that is created for a supporting ad network (see more).

On top of this, our custom events API allows you to track specific events within your playable that will help you understand the user flow and drop off points within the ad.

All custom events are in the Luna.Unity.Analytics namespace.

Warning

When implementing custom events, please avoid logging any event during the initialisation phase of your game i.e. in the Awake method.

Custom event limits​

In order to avoid misuse or user-code errors, Unity Playworks Plugin enforces two limits on custom events.

  • 256 events logged per playable session

You can log up to 256 events in a given playable session (per user). After 256 logged events, any subsequent events will be dropped by the server.

  • 32 events per unique event name

You can log up to 32 events per unique event in a given playable session (per user). After 32 logged events, any subsequent events will be dropped by the server.

Pre-defined custom events​

Unity Playworks Plugin provides a number of commonly used and useful custom events to be used in your playable. These events will also have pre-built reporting template in Unity Playworks's Insights pages.

Each event has a name and optional integer parameter.

note

The optional integer parameter is NOT optional when passing a string as the first parameter to the LogEvent function instead of an EventType.

  • TutorialStarted - the user interacted with the tutorial.
  • TutorialComplete - the user has completed the tutorial.
  • LevelStart - a level was started.
  • LevelWon - the user won a level.
  • LevelFailed - the user failed a level.
  • LevelRetry - a user retried a level.
  • Score - submit a score to Unity Playworks Plugin Insights.
  • EndCardShown - the end card was shown.

Implementation Example​

public void GameEnded() {

    int levelReached = // level number reached by player, 0 if they failed on the first //

    if( levelReached > 0 ) {
        Luna.Unity.Analytics.LogEvent(Luna.Unity.Analytics.EventType.LevelWon, levelReached);
    }
    else {
        // The integer value bares no meaning here, so any value will do.
        Luna.Unity.Analytics.LogEvent(Luna.Unity.Analytics.EventType.LevelFailed, 0);
    }

    // Log the game ended event
    Luna.Unity.LifeCycle.GameEnded();

    ShowEndCard();
}

public void ShowEndCard() {

    // Show the end card

    Luna.Unity.Analytics.LogEvent(Luna.Unity.Analytics.EventType.EndCardShown);
}

Open custom events​

If your game has specific experiences which you want to measure, and the needs aren't met via one of the pre-defined events detailed above, you can also use your own custom events.

This API allows you to pass in any string, which will be logged and available for reporting in Unity Playworks Plugin Insights.

Implementation Example​

For example, you could log an event with different values based on what threshold the user's score reached:


public void LevelOver() {

    int PlayerScore = // Score calculation //

    if( PlayerScore < 500 ){
        // In this example the value will not denote the exact score, but will be a representation of the threshold.
        Luna.Unity.Analytics.LogEvent("score_achieved", 0);
    }

    if( PlayerScore < 1000 && PlayerScore > 500){
        Luna.Unity.Analytics.LogEvent("score_achieved", 500);
    }

    if( PlayerScore < 1500 && PlayerScore > 1000){
        Luna.Unity.Analytics.LogEvent("score_achieved", 1000);
    }

    // etc.
}

We recommend not passing in values that can widely vary like a player's score, as each unique value will create its own unique event. So if a score can vary between all values in between 0 - 1000, you could potentially end up with 1000 different events.

Testing Custom Events in Unity Playworks​

You can find out more on this here.

Events Settings​

You can find out more about these settings here.