Event Filter

Depending on your game, you may not need to fire all events all the time. Events cost money, so if some events aren’t needed right now, use our Event Filter to restrict events to the right level. All event are assigned a priority P0 (critical) to P5 (nice to have).

Introduction

From LionAnalytics 2.5+, events are now filtered on the client side before being fired. This was introduced to help reduce overall data costs. With this system, you do not need to modify your in-game event code when you aren’t doing analysis and want to pause or adjust the volume of events being collected.

We recommend setting up a Remote Configuration variables for Priority Level and Whitelist Countries, then connecting those variables with the LionAnalytics override methods:

• SetWhitelistPriorityLevel()
• AddWhitelistCountries()

The filter will decide whether to fire an event based on:

• the event name
• the player’s country
• the default filter settings (below)
• the overridden settings (below)

This means that not all events may be fired and you may be missing events when viewing LionAnalytics QA Tool or Looker dashboards.

This is normal, expected, and depends on your filter settings and country from where you are testing.

If someone (QA for example) reports missing events, first check your current filter setting and the country where they are testing to determine if this event should be showing up.

Default Filter Settings

• The default filter settings are defined in a remote file here.

• This file is downloaded and used by the Lion Analytics package. It is cached for offline use and refreshed every 24h.

• This file contains:

  • whitelistPriorityLevel - Defines which events can be fired from whitelisted countries
  • defaultPriorityLevel - Defines which events can be fired from non-whitelisted countries
  • eventsPriorityLevels - Defines the priority of each event.
  • whitelistCountries - Defines the list of countries that are considered whitelist, and using whitelistPriorityLevel instead of defaultPriorityLevel.

• An event will be fired if the priority level associated with this event is lower or equal to the priority level associated with the player’s country tier (whitelist or default).

  So a PX event will be fired if:

  • player’s country is in whitelistCountries and whitelistPriorityLevel is PX+

    OR

  • player’s country is not in whitelistCountriesand defaultPriorityLevel is PX+

  More examples can be found in the Examples section below.

• The event priority levels are ordered from highest to lowest priority of the event.

  • P0 - always fired from all goes

Override Methods

You can override two settings of the filter locally:

• The countries in the whitelist
• The priority level for countries in the whitelist

Call the two override methods below when your game starts (in every session). These functions can be called anytime:

• If called before Analytics package initialization, the values will be stored and used during the initialization.
• If called after initialization, the settings will be updated for all subsequently fired events.

The parameters you pass to these methods should ultimately be controlled by remote configs (Satori, Firebase…).

SetWhitelistPriorityLevel()

• Overview: Set Priority level for whitelisted countries to send events
• Returns: void
• Parameters:

Signature

LionAnalytics.SetWhitelistPriorityLevel(EventPriorityLevel priorityLevel)

Example

LionAnalytics.SetWhitelistPriorityLevel(EventPriorityLevel.P4);

This will set the priority level for whitelisted countries to P4. This means events P0-P4 will be fired for these countries. You can only override to a higher level than the one in the default settings file.

This method is case-sensitive, please provide uppercase letters.

AddWhitelistCountries()

• Overview: Add to the list of whitelist countries to fire events
• Returns: void
• Parameters:

Signature

LionAnalytics.AddWhitelistCountries(List<string> countryCodes)

The countryCodes must be 2-letters codes using the standard ISO 3166-1 alpha-2.

Example

LionAnalytics.AddWhitelistCountries(new List<string>() {"in", "tr"});

This will add India and Turkey to the whitelistCountries. So if the player is in one of these countries, they will now be using whitelistPriorityLevel instead of defaultPriorityLevel.

You cannot remove countries from the default list.

Key Takeaways

• Each event has a priority level
• There are two country tiers: whitelisted & non-whitelisted
  • Whitelisted countries use whitelistPriorityLevel
  • Non-whitelisted countries use defaultPriorityLevel
• Default event priority levels and whitelisted geos are loaded from default settings file - No Action Needed
• Developers have two methods to override the settings of the events filter:
  • AddWhitelistCountries()
  • SetWhitelistPriorityLevel()
• Note only whitelisted GEOs will fire events with the following priority:
  • P1 events are fired when SetWhitelistPriorityLevel() is set to P1-P5
  • P2 events are fired when SetWhitelistPriorityLevel() is set to P2-P5
  • P3 events are fired when SetWhitelistPriorityLevel() is set to P3-P5
  • P4 events are fired when SetWhitelistPriorityLevel() is set to P4-P5
  • P5 events are fired when SetWhitelistPriorityLevel() is set to P5
• We recommend hooking up Remote Config variables so you can change these values remotely without requiring a build and release.

Examples

Example #1

• Situation:
  • The game code calls SetWhitelistPriorityLevel() with parameter P3
  • The player is in China
  • The game fires interstitial_show
• Result:
  1. You overrode the default level from P1 to P3. So all P0, P1, and P3 events are expected to show up for valid geos.
  2. China is in the whitelist countries - so China is valid, and we don’t expect the event to be blocked based on location.
  3. Reviewing the default settings file, we see that interstitial_show is P1.
  4. Since P1 ≤ P3 and China is valid, the event will be fired.

Example #2

• Situation:
  • The game code calls SetWhitelistPriorityLevel() with parameter P3.
  • The player is in China
  • The game fires interstitial_show_fail
• Result:
  1. You overrode the default level from P1 to P3. So all P0, P1, and P3 events are expected to show up for valid geos.
  2. China is in the whitelist countries - so China is valid, and we don’t expect the event to be blocked based on location.
  3. Reviewing the default settings file, we see that interstitial_show_fail is P4.
  4. While China is valid, P4 > P3, so the event will not fire.

Example #3

• Situation:
  • The game code calls SetWhitelistPriorityLevel() with parameter P4.
  • The player is in China
  • The game fires interstitial_show_fail
• Result:
  1. You overrode the default level from P1 to P4. So all P0, P1, P3, and P4 events are expected to show up for valid geos.
  2. China is in the whitelist countries - so China is valid, and we don’t expect the event to be blocked based on location.
  3. Reviewing the default settings file, we see that interstitial_show_fail is P4.
  4. China is valid and P4 ≤ P4, so the event will fire.

Example #4

• Situation:
  • The game code calls SetWhitelistPriorityLevel() with parameter P4.
  • The player is in Turkey
  • The game fires interstitial_show_fail
• Result:
  1. You overrode the default level from P1 to P4. So all P0, P1, P3, and P4 events are expected to show up for valid geos.
  2. Turkey is not a whitelist countries. Unless you call AddWhitelistCountries to add Turkey, only P0 and P1 events from Turkey will be seen.
  3. Reviewing the default settings file, we see that interstitial_show_fail is P4.
  4. While you set the override to P4, and this event is P4, Turkey is not whitelisted so only P0 and P1 events will fire from Turkey. So, this event will not fire.

Example #5

• Situation:
  • The game code calls SetWhitelistPriorityLevel() with parameter P4.
  • The game code calls AddWhitelistCountries with parameter tr (Turkey)
  • The player is in Turkey
  • The game fires interstitial_show_fail
• Result:
  1. You overrode the default level from P1 to P4. So all P0, P1, P3, and P4 events are expected to show up for valid geos.
  2. You overrode the default country whitelist and added Turkey, so Turkey is now valid. We don’t expect the event to be blocked based on location.
  3. Reviewing the default settings file, we see that interstitial_show_fail is P4.
  4. Turkey is valid and P4 ≤ P4, so the event will fire.