Unity Analytics SDK

Analytics

Alongside SmartFloors ad optimization, the Metica SDK provides first-party event collection for player behaviour, monetization, and user state. Analytics shares the SDK's configuration and initialization — once the analytics package is installed and the SDK is initialized, log events through MeticaSdk.Analytics:

MeticaSdk.Analytics.LogCustomEvent("levelComplete", new Dictionary<string, object>
{
    ["levelIndex"] = 12,
    ["stars"] = 3
});

Prerequisites

Before using Metica Analytics, you need:

1. API Key — obtained from the Metica platform

2. App ID — obtained from the Metica platform

3. A MAX SDK Key, obtainable from the AppLovin platform (only required when initializing the SDK with ads)

Installation

If you haven't done so already, install the Metica SDK first by following the Unity SDK integration guide. Analytics is part of the same SDK package — no separate SDK installation is required.

The Analytics feature requires one additional package on top of the Metica SDK:

1. Download com.metica.analytics.abstractions-1.0.0.tgz

2. In Unity Editor, go to Window → Package Manager

3. Click the + button in the top-left corner and select Add package from tarball...

4. Select the downloaded com.metica.analytics.abstractions-1.0.0.tgz

The SDK detects the package automatically — once it is installed, the Analytics API is compiled in and MeticaSdk.Analytics becomes available. No scripting defines need to be set manually.

Initialization

Analytics does not need to be initialized separately. The SDK is initialized once — when the analytics package is installed, the standard MeticaSdk.Initialize / MeticaSdk.InitializeAsync call also initializes Analytics, and MeticaSdk.Analytics is ready to use after it completes. The early-session flow below is only needed if you want Analytics available earlier in the app lifecycle than your standard SDK initialization.

var config = new MeticaInitConfig("YOUR_API_KEY", "YOUR_APP_ID", "YOUR_USER_ID");
var mediationInfo = new MeticaMediationInfo(MeticaMediationType.MAX, "YOUR_MAX_SDK_KEY");
var initResponse = await MeticaSdk.InitializeAsync(config, mediationInfo);

Capturing early-session events

Some integrations defer InitializeAsync until later in the boot flow — waiting on user consent, a loading screen, or remote configuration. Events cannot be logged before the SDK is initialized, so early-session events such as install and sessionStart would be lost.

For this case only, initialize Analytics on its own as soon as the app starts. Analytics is fully active from this call — events are recorded and delivered normally. The later InitializeAsync call adds SmartFloors on top of the running SDK:

// At app start: Analytics only
var config = new MeticaInitConfig("YOUR_API_KEY", "YOUR_APP_ID", "YOUR_USER_ID");
MeticaSdk.InitializeAnalytics(config);

// ... early-session events (install, sessionStart, ...) can be logged from here on ...

// Later, after consent / when ads are needed: add SmartFloors
var mediationInfo = new MeticaMediationInfo(MeticaMediationType.MAX, "YOUR_MAX_SDK_KEY");
var initResponse = await MeticaSdk.InitializeAsync(config, mediationInfo);

Pass the same MeticaInitConfig to both calls. If the second call supplies a different configuration, the SDK keeps the configuration from the first call and logs a warning.

If you initialize the SDK at app start (the standard flow), you do not need InitializeAnalytics — skip this and use the single InitializeAsync call above.

User identity

Every event carries a userId. You can either:

• Supply your own stable user ID via MeticaInitConfig, or

• Let the SDK generate one. The SDK derives a deterministic UUID from a hash of a device identifier combined with your appId, so the generated ID remains consistent for a given device and app across launches. On Android the underlying identifier survives app reinstalls; on iOS it can be reset by the OS when all apps from the same vendor are uninstalled.

If you have your own account system, supplying your own ID is recommended so that events can be joined with your other data sources.

Sessions

A session represents a continuous span of user activity within your game.

• Session start — the first activity after launch, or after at least 30 minutes of inactivity.

• Session end — the game stops producing events for 30 minutes.

• Session length — time of last recorded activity minus time of session start.

The SDK derives sessionCount and lastSessionLength from this definition and attaches them to every event automatically (see Environment attributes). Note that the sessionStart event is logged by your game (see sessionStart) — the SDK's session bookkeeping runs regardless, but the event itself is not emitted automatically.

Event schema

Events fall into two categories:

• Core events — predefined events with a fixed schema, handled by the SDK with minimal developer input.

• Custom events — developer-defined events for use cases not covered by core events.

Base properties

Every event, core or custom, carries the following properties. All of them are populated automatically by the SDK — you never set them directly.

Property	Type	Description
eventType	string	Identifies the type of event (e.g. purchase, or your custom event name)
eventId	string	Unique ID of this event, generated by the SDK
appId	string	Your Metica app ID
eventTime	number	Unix timestamp in milliseconds, set by the SDK at logging time
userId	string	The user ID (supplied or SDK-generated, see User identity)
customPayload	object	Optional developer-supplied properties (see rules below)

In addition, the SDK attaches the environment attributes to every event. In the delivered payload these appear as top-level fields on the event, alongside the base properties above.

customPayload rules:

• A single flat object — nested objects are not permitted.

• Values must be primitives (string, number, boolean) or arrays of up to 100 elements of the same primitive type.

• At most 100 properties per payload. String values longer than 200 characters are truncated. The same limits apply to userStateAttributes.

• Allowed on all core events except fullStateUpdate and partialStateUpdate.

• For custom events, customPayload carries the event's properties.

Property type consistency: once a property has been sent with a specific type, all future events — from your game or any other game in your organization — must use the same type for that property. Violating this causes errors and missing data in the ingestion pipeline. To change a property's type, stop sending it and introduce a new property name.

Environment attributes

The SDK automatically collects the following properties and attaches them to every event:

Attribute	Type	Platform	Description
appVersion	string	All	Host app's version (e.g. 1.4.2)
meticaNativeSdk	string	All	Metica native SDK version
meticaUnitySdk	string	All	Metica Unity SDK version (when used from Unity)
platform	string	All	android or ios
osVersion	string	All	Operating system version (e.g. 14, 17.4)
buildNumber	string	All	OS build identifier
deviceModel	string	All	Device model identifier (e.g. Pixel 7, iPhone15,2)
deviceManufacturer	string?	Android only	Hardware manufacturer (e.g. Google, Samsung)
deviceType	string	All	phone or tablet
deviceMemory	long	All	Total device RAM in megabytes
locale	string	All	BCP-47 language tag (e.g. en-US)
localTimezone	string	All	IANA time zone identifier (e.g. Europe/London)
country	string?	All	ISO 3166-1 alpha-2 country code, lowercased
storeCountry	string?	iOS only	App store storefront country (when available)
gaid	string?	Android only	Google Advertising ID (lowercased); null when unavailable
idfa	string?	iOS only	Apple Identifier For Advertisers; null when tracking is unauthorized
idfv	string?	iOS only	Apple Identifier For Vendor; null when tracking is unauthorized
sessionCount	long	All	Number of sessions started by this user on this device
lastSessionLength	long	All	Duration of the previous session, in seconds

Attributes marked nullable (?) may be absent from the payload when the platform cannot resolve them — for example gaid/idfa/idfv when the user has not granted tracking consent.

Core events

Core events have a fixed schema. The base properties above are always included and are omitted from the field lists below.

purchase

Log a completed (or failed) in-app purchase.

Field	Type	Required	Description
productId	string	yes	Store product identifier
currencyCode	string	yes	ISO 4217 currency code (e.g. USD)
totalAmount	number	yes	Purchase amount in the given currency
status	string	yes	Purchase outcome (e.g. completed, failed)
errorCode	string	no	Error code when the purchase failed
referenceId	string	no	Store transaction / receipt reference

MeticaSdk.Analytics.LogPurchaseEvent(
    productId: "com.yourgame.gems_100",
    currency: "USD",
    amount: 4.99,
    status: "completed",
    errorCode: null,
    referenceId: "GPA.1234-5678",
    customPayload: null);

sessionStart

Marks the beginning of a session. No additional fields.

MeticaSdk.Analytics.LogSessionStartEvent(customPayload: null);

install

Log this once, on the first launch after installation.

Field	Type	Required	Description
appVersion	string	yes	App version at install time (set by the SDK)

MeticaSdk.Analytics.LogInstallEvent(customPayload: null);

impression

Log an ad impression, including the revenue it generated. Use this only for ad sources that are not mediated through the Metica SDK — revenue for ads shown through the Metica SDK is reported automatically (as estimatedAdRevenue events).

Field	Type	Required	Description
value	number	yes	Revenue of the impression in USD (e.g. 0.00555)
impressionType	string	yes	Ad format (e.g. Rewarded, Interstitial)
mediator	string	yes	Mediation platform (e.g. AppLovin)
source	string	yes	Ad network that served the ad (e.g. ironSource)
placement	string	no	Placement in your game (e.g. LevelSuccess)

MeticaSdk.Analytics.LogImpressionEvent(
    value: 0.00555,
    type: "Rewarded",
    mediator: "AppLovin",
    source: "ironSource",
    placement: "LevelSuccess",
    customPayload: null);

fullStateUpdate

A snapshot of all attributes of the user state, typically sent once per session. It replaces all previously sent user state attributes. customPayload is not allowed on this event.

Field	Type	Required	Description
userStateAttributes	object	yes	Map of attribute name → value

MeticaSdk.Analytics.LogFullStateUpdateEvent(new Dictionary<string, object>
{
    ["playerLevel"] = 42,
    ["softCurrencyBalance"] = 1200,
    ["vipTier"] = "gold"
});

partialStateUpdate

Updates a subset of user state attributes as the player progresses. customPayload is not allowed on this event.

Field	Type	Required	Description
userStateAttributes	object	yes	Map of the changed attributes only

MeticaSdk.Analytics.LogPartialStateUpdateEvent(new Dictionary<string, object>
{
    ["playerLevel"] = 43
});

Custom events

Custom events let you track game-specific behaviour not covered by core events. A custom event consists of the base properties plus your properties, carried in customPayload.

MeticaSdk.Analytics.LogCustomEvent("earnAsset", new Dictionary<string, object>
{
    ["asset"] = "coin",
    ["source"] = "monthlyDrive",
    ["type"] = "rewarded",
    ["amount"] = 12
});

Rules:

• Event names must be camelCase, letters only, no digits and no special characters (e.g. levelComplete, itemPurchased). This is enforced — events with invalid names are dropped.

• The core event names are reserved and must not be used: purchase, impression, sessionStart, install, fullStateUpdate, partialStateUpdate.

• Properties follow the customPayload rules above: primitives or arrays of primitives, no nested objects, at most 100 properties, and stable types per property name.

Validation and delivery

• All events are schema-validated before transmission. Events that fail validation are dropped and not retried.

• Validated events are batched, persisted locally, and delivered with automatic retry — events are not lost to transient network failures or app restarts.

Building a custom analytics wrapper

Studios that ship many titles often want a shared, internal analytics library that standardises how each game describes its world while still routing events through Metica. The SDK supports this pattern through the Metica.Analytics.Abstractions package installed above.

Layer	Owner	Changes often?	Purpose
Metica.Analytics.Abstractions	Metica	Rarely	Tiny, stable contract — the IMeticaAnalytics interface
Metica Unity SDK	Metica	Often	Full implementation — transport, retries, device info, ad mediation
Your wrapper library	Your studio	As needed	Game- or genre-specific helpers that map gameplay state to event payloads

Your wrapper depends only on the abstractions package, not on the full SDK — SDK upgrades do not require rebuilding or changing your wrapper code. MeticaSdk.Analytics implements IMeticaAnalytics, so your wrapper accepts the interface in its constructor and never references the concrete SDK:

using Metica.Analytics.Abstractions;

public class PuzzleAnalytics
{
    private readonly IMeticaAnalytics _analytics;

    public PuzzleAnalytics(IMeticaAnalytics analytics)
    {
        _analytics = analytics;
    }

    public void LogLevelEndOfferImpression(string offerId, int levelIndex, int stars)
    {
        _analytics.LogCustomEvent("puzzleLevelEndOfferImpression", new Dictionary<string, object>
        {
            ["offerId"] = offerId,
            ["levelIndex"] = levelIndex,
            ["stars"] = stars,
        });
    }
}

// Wiring it up after initialization:
var puzzle = new PuzzleAnalytics(MeticaSdk.Analytics);

API reference

The full logging API, available via MeticaSdk.Analytics after initialization. Nullable parameters (?) accept null but must still be passed explicitly:

public interface IMeticaAnalytics
{
    void LogPurchaseEvent(
        string productId,
        string currency,
        double amount,
        string status,
        string? errorCode,
        string? referenceId,
        Dictionary<string, object>? customPayload);

    void LogSessionStartEvent(Dictionary<string, object>? customPayload);

    void LogInstallEvent(Dictionary<string, object>? customPayload);

    void LogImpressionEvent(
        double value,
        string type,
        string mediator,
        string source,
        string? placement,
        Dictionary<string, object>? customPayload);

    void LogFullStateUpdateEvent(Dictionary<string, object> attributes);

    void LogPartialStateUpdateEvent(Dictionary<string, object> attributes);

    void LogCustomEvent(string eventName, Dictionary<string, object>? properties);
}

Initialization method:

• InitializeAnalytics(MeticaInitConfig) → void — analytics-only initialization for capturing early-session events; InitializeAsync later upgrades the same instance to full mode.