Meta Developers

In-World Analytics enables creators to store data regarding events that occur within their worlds. Creators can then analyze this information to learn how players inhabit and use their creations, and to iterate and improve their worlds.

Note: You can validate your analytics set-up in edit mode using our validation tools, but In-World Analytics from public use will only appear once you have more than 10 Daily Active Users (DAU) visiting your world.

In-world analytics is comprised of two parts:

Data storage to store the data from events in the world
A TypeScript API to pass the data to the data store

Meta has created a starter kit, Turbo Analytics, available in the asset library that bundles the two parts.

In this tutorial you will learn:

How to add the TypeScript assets to simplify the integration of in-world analytics to your world
How to use TypeScript with the Analytics Manager to store event data about your world

You can create a new world using the Chop ‘N Pop Graveyard Bash Extended template to see a finished example.

Prerequisites

We are going to explore adding in-world analytics to an existing game - Chop ‘n’ Pop Graveyard Bash - as our starting point. Before you begin, please verify that you have access to your own copy of the Chop ‘N Pop: Graveyard Bash world. For more information, see Access Tutorial Worlds.

Note: This tutorial assumes that you are familiar with the Desktop Editor, a desktop application for world building in Meta Horizon Worlds. If you are new to the Desktop Editor, you might want to start with the Intro to Desktop Editor and TypeScript tutorial. See Module 1 - Intro to Desktop Editor and TypeScript.

If this is your first time exploring your own copy of Chop ‘n’ Pop Graveyard Bash, it is recommended that you go through the Chop ‘N Pop Graveyar Bash sample world tutorial before this tutorial.

Adding The Analytics Library

Toggle the horizon/analytics API
1. Open the Settings menu under the scripts tab
2. Choose API in the left hand menu
3. Toggle on horizon/analytics
Import the Turbo Analytics template
1. Open the Asset Library
2. Navigate to the Interactive category
3. Find Turbo Analytics

Turbo Analytics Template

The Turbo Analytics template includes the following entities:

TurboAnalytics.ts (TypeScript Script): This script manages sending data from the world to the TypeScript API.
TurboAreaTrigger.ts (TypeScript Script): This script can be added to a TriggerGizmo entity in the world, and configured to include the name of the area. The script records AreaEnter and AreaExit analytics events when a player enters and exits the TriggerGizmo.
TurboDiscoveryMadeTrigger.ts (TypeScript Script): This script can be added to a TriggerGizmo entity in the world, and configured to include the name of a discovery event. The script records DiscoveryMade analytics events when a player enters the TriggerGizmo.

Turbo Analytics Host (Text): This entity hosts the TurboAnalytics script and should be hidden at runtime by moving below the world or set to invisible.

Configure the Analytics Manager script for development

In-world analytics are a background activity that should have minimal impact on the player’s experience of a world. As such, it can be challenging to know whether the analytics have been setup correctly according to your needs and the requirements of the world.

In order to understand what events are being sent to the in-world analytics engine it is recommended to turn on in-world analytics logging whilst you are implementing and/or testing the analytics into your world. To turn on in-world analytics logging:

Open the TurboAnalytics.ts Script in a script editor.
Change line 15 so that it reads as follows:

export const TURBO_DEBUG =
  true; /** TODO (Creator): IMPORTANT!!! Set to False before Release **/

Edit the onDebugTurboPlayerEvent function so that it prints the player and event to the console when something is sent to the in-world analytics API:

onDebugTurboPlayerEvent(\_player: hz.Player, \_eventData: EventData, \_action: Action): void {
   console.log(`🚀 TURBO: Debugging Turbo Player Event: ${_player.name.get()}: ${Action[_action].toString()}`);
}

Open your developer console drawer and make sure it is clear by pressing Clear
Preview the world Observe that Turbo events are logging correctly in the console. You should see some initial in-world analytics events being printed to the console

Adding A World Data Model

In TypeScript As we can use information from our In-World Analytics to guide improvements in the world, it is good practice to move some of the variables that allow us to easily tweak and update the balancing of the world into a single file.

Use these steps to create your own World Data Model:

Open the Scripting menu Create new Script
Name the script GameConstants.ts
Open the script in your Script editor
Replace the entire contents of the script with the following:

export const GameConstants = {};

Summary

In this module, you learned what in-world analytics are, how to add some of the core libraries to your world, and enabled debugging and printing analytics events to your console. You’ve also added a new Script which you will use to store tweakable variables for your world.

In the next module, you will explore integrating the AnalyticsManager to the Chop ‘N Pop Graveyard Bash game logic, and recording events through the Analytics TypeScript API.