Step-by-Step Example Integration

Table of Contents

• Overview
• Key Concept: Context-First Events
• Game Name
• Game Description
• Integration Scenarios
  • Scenario 1: First Launch & Consent
  • Scenario 2: Player Registration & Sign-In
  • Scenario 3: Entering Main Menu & Changing Language
  • Scenario 4: FTUE Milestones Tracking
  • Scenario 5: Level Start & Completion
  • Scenario 6: In-Game Combat & Power-Ups
  • Scenario 7: Store Purchases (IAP)
  • Scenario 8: Daily Resets
  • Scenario 9: Non Unity.UI Buttons & Window Flow
  • Scenario 10: Advanced Item & Goal Tracking
  • Scenario 11: Custom Error Reporting

Overview

This page provides a comprehensive example of integrating the KeewanoSDK APIs into a Unity sample game, giving developers a clear, step-by-step reference for a flawless implementation.

Key Concept: Context-First Events

Traditional analytics repeat lots of properties on every event (level, device, A/B group, campaign, …).
Keewano DB keeps a single, ordered event stream per user.
Once context enters the stream, the system automatically reuses it as context for every subsequent event - so you DO NOT need to re-send the info, but only send state changes.

For example:

Scenario	Legacy payload	Keewano call
Level 15 won	{event:"level_win", level:15, difficulty:"medium", segment:"A/B_1", device:"iPhone13"}	KeewanoSDK.ReportLevelWin(15);
Banner store opened	{event:"store_open", placement:"main_banner", utm_campaign:"SpringSale"}	KeewanoSDK.ReportWindowOpen("Store_MainBanner");
FTUE milestone step 3	{event:"tutorial_step", step:3, ab_group:"tutorial_redesign"}	KeewanoSDK.ReportOnboardingMilestone("Step 3");

Game Name

Space Shooter

Game Description

Space Shooter is a top-down shooter in which the player pilots a spaceship through ten levels to save the galaxy.

• Goal: Defeat enemy waves before time runs out, collect data cores to upgrade your ship and beat the final boss.
• Progression: Clear levels to unlock ship skins, weapons, and power-ups.
• Currencies & Rewards:
  • Crystals (premium currency acquired via IAP)
  • Metal Shards (crafting material earned by defeating enemies)
  • Data Cores (warp-gate charge modules dropped by elite foes or hidden in secret crates)
  • Fuel Cells (consumable energy for your ship’s special abilities, refills at UTC midnight)
  • Ship Skins (cosmetic items unlocked by level completion or purchased with Crystals)
  • Weapons (standard and special armaments unlocked through progression or crafted with Metal Shards)
  • Power-Ups (temporary in-combat boosts earned in levels or bought in the store)
• Menus & Windows:
  • Main Menu (The landing screen when the game launches. Options: Play, Tutorial, Settings, Store, Inventory, and Leaderboard)
  • Pause Menu (Accessible during gameplay. Options: Resume, Restart, Quit)
  • Galactic Store (In-game shop where players spend Crystals or Metal Shards to buy ship skins, weapon upgrades, and limited-time bundles)
  • Inventory (Displays all owned ship skins, weapons, power-ups, and Consumables [Fuel Cells, Data Cores]. Allows equip/upgrade actions)
  • Leaderboard (Shows top player rankings for time-trial scores, fastest level clears, and highest overall campaign progress)
• Win/Lose:
  • Win: Boss Health → 0
  • Lose: Ship Health → 0 or time runs out

Integration Scenarios

Scenario 1: First Launch & Consent

Player Action: Installs the game and opens it for the first time.
Developer: Split responsibilities into clear initialization stages:

• Consider the User Consent setting.
  

  Attention

  This is relevant if your project or regional requirements demand explicit player consent before any analytics data is sent.
  See Data Privacy for more details about User Consent.

  If Player consent is required in your game, set it in the following way:

  bool consent = ShowConsentDialog();
  KeewanoSDK.SetUserConsent(consent);

  Note

  If consent was denied, no analytics data will ever be sent.

• Consider marking devices as testers for QA purposes:

  void ConfigureTestUser()
  {
      KeewanoSDK.MarkAsTestUser("John Doe");
  }

  Note

  We recommend using this feature to isolate test data.

• Retrieve anonymous install ID for later attribution or debugging:

  Guid installId = KeewanoSDK.GetInstallId();
  // send installId to your backend or attach to crash reports

• Consider campaign attribution:

  void OnCampaignDetected(string campaignSource)
  {
      // If user has installed campaign attribution, report it
      if (!string.IsNullOrEmpty(campaignSource))
          KeewanoSDK.ReportInstallCampaign(campaignSource);
  }

Scenario 2: Player Registration & Sign-In

Player Action: Opens the Sign Up form, fills details (email/password), taps Register.
Developer: After your auth service returns a new playerId:

void OnRegistrationSuccess(Guid playerId)
{
    // Associate future events with this persistent user ID
    KeewanoSDK.SetUserId(playerId);
}

Note

PlayerId can be a Guid or UInt64 value, according to your game needs.

void AssignToAbGroup(char abGroup)
{
    // Record which A/B test cohort they belong to
    KeewanoSDK.ReportABTestGroupAssignment("NewPowerupExperiment", abGroup);
}

Scenario 3: Entering Main Menu & Changing Language

Player Action: After login, the Main Menu pops up. The player opens Settings and switches the language to French. Then closes Settings.
Developer: In your MainMenuHandler:

void OnMainMenuOpened()
{
    KeewanoSDK.ReportWindowOpen("MainMenu");
}
 
void OnMainMenuClosed()
{
    KeewanoSDK.ReportWindowClose("MainMenu");
}
 
void OnSettingsOpened()
{
    KeewanoSDK.ReportWindowOpen("SettingsWindow");
}
 
void OnSettingsClosed()
{
    KeewanoSDK.ReportWindowClose("SettingsWindow");
}

Attention

You do NOT have to call KeewanoSDK.ReportWindowOpen/ KeewanoSDK.ReportWindowClose manually if you add the 'KeewanoWindow' component to your UI GameObject.
It will automatically track window open/close events.

See the Windows and Popups section for more details.

void OnLanguageChanged(string newLangCode)
{
    KeewanoSDK.ReportGameLanguage(newLangCode);
}

Scenario 4: FTUE Milestones Tracking

Player Action: During the first session the player completes key milestones.
Developer: Hook into your milestones points:

void OnEnemyKill()
{
    if (KilledFirstBoss)
        KeewanoSDK.ReportOnboardingMilestone("Killed The First Enemy");
}
 
void OnRewardCollection()
{
    if (CollectedFirstReward)
        KeewanoSDK.ReportOnboardingMilestone("Collected First Reward");
}
 
void OnLevelStart(uint levelNumber)
{
    KeewanoSDK.ReportOnboardingMilestone($"Level_{levelNumber} Started");
}
 
void OnLevelWin(uint levelNumber)
{
    KeewanoSDK.ReportOnboardingMilestone($"Level_{levelNumber} Win");
}
 
void OnIAP()
{
    if (FirstIAP)
        KeewanoSDK.ReportOnboardingMilestone("First In App Purchase");
}
 
void OnTutorialStart()
{
    KeewanoSDK.ReportOnboardingMilestone("Tutorial Started");
}
 
void OnTutorialQuitMidway()
{
    KeewanoSDK.ReportOnboardingMilestone("Quit Tutorial");
}
 
void OnTutorialComplete()
{
    KeewanoSDK.ReportOnboardingMilestone("Tutorial Completed");
}

Note

Important: Do NOT use custom events to report onboarding milestones.
Using KeewanoSDK.ReportOnboardingMilestone API fuels the Keewano AI's FTUE funnel so it can flag tutorial drop-offs automatically.

Scenario 5: Level Start & Completion

Player Action: From Main Menu the player taps Play, chooses Level 1, fights through 5 waves and win/lose the level
Developer:

Attention

In this scenario you need to use custom events, see Custom Events for more details regarding custom events generation.

In your LevelManager:

void OnLevelStart(uint levelNumber)
{
    // Custom event usage
    KeewanoSDK.ReportLevelStart(levelNumber);
}
 
void OnLevelEnd(uint levelNumber)
{
    // Custom event usage
    KeewanoSDK.ReportLevelEnd(levelNumber);
}
 
void OnLevelWin(uint levelNumber)
{
    // Custom event usage
    KeewanoSDK.ReportLevelWin(levelNumber);
}
 
void OnLevelLose(uint levelNumber)
{
    // Custom event usage
    KeewanoSDK.ReportLevelLose(levelNumber);
}

Note

• Always pass the exact same IDs (i.e. levelNumber value) to these calls so that progression analytics remain accurate and consistent. This will allow the Keewano AI agents build and explore an informative progression report.
  
  
• Always pass raw values directly to the SDK APIs, never as formatted strings:
  ✅ KeewanoSDK.ReportLevelStart(15) - pass numbers directly
  ⛔ KeewanoSDK.ReportLevelStart("15") - don't pass numbers as strings
  ✅ KeewanoSDK.ReportEnemyKilled("Orc") - strings should be actual strings
  ⛔ KeewanoSDK.ReportEnemyKilled("enemy_type=Orc") - avoid formatted labels
  
  
• Avoid wrapping values in labels or descriptive text:
  ✅ KeewanoSDK.ReportLevelWin(10)
  ⛔ KeewanoSDK.ReportLevelWin("level = 10")
  ✅ KeewanoSDK.ReportEnterMainLevel(3)
  ⛔ KeewanoSDK.ReportEnterMainLevel("stage_3")

Scenario 6: In-Game Combat & Power-Ups

Player Action: Destroys regular enemies, then uses the “Hyper Beam” power-up before fighting strong “Omega Crusher” enemy.
Developer: In your CombatController:

void OnEnemyDestroyed(string enemyType)
{
    // Custom event usage
    KeewanoSDK.ReportEnemyDefeated(enemyType);
}
 
void OnPowerUpUsed(string powerName)
{
    // Optional - Custom event usage
    KeewanoSDK.ReportPowerUpUsed(powerName);
 
    Keewano.Item[] usedItem = { new Keewano.Item("Hyper Beam") };
    KeewanoSDK.ReportItemsExchange("OmegaCrusherCombat", usedItem, null);
}

Note

Always Prefer using KeewanoSDK.ReportItemsExchange and KeewanoSDK.ReportItemsReset instead (or in addition to) a decidacted custom event.
It will help Keewano AI to track the game balance.

Scenario 7: Store Purchases (IAP)

Player Action: Opens Galactic Store, buys 500 crystals for $4.99.
Developer: After successful IAP callback:

void OnGalacticStoreOpen()
{
    KeewanoSDK.ReportWindowOpen("GalacticStore");
}
 
void OnIAPSuccess(string product, uint priceInUsdCents)
{
    // product is the product ID as defined in app stores (Apple App Store, Google Play)
    KeewanoSDK.ReportInAppPurchase(product, priceInUsdCents);
    
    // Track the virtual currency received
    Keewano.Item[] purchasedItems = { new Keewano.Item("Crystals", 500) };
    KeewanoSDK.ReportItemsExchange(product, null, purchasedItems);
}
 
void OnGalacticStoreClose()
{
    KeewanoSDK.ReportWindowClose("GalacticStore");
}

Scenario 8: Daily Resets

Auto Action: At UTC midnight, Daily Fuel resets to 100.
Developer: In your DailyResetService:

void OnDailyReset()
{
    Keewano.Item[] dailyFuelReset = { new Keewano.Item("FuelCell", 100) };
    KeewanoSDK.ReportItemsReset("DailyReset", dailyFuelReset);
}

Scenario 9: Non Unity.UI Buttons & Window Flow

Player Action: Within Main Menu, taps Leaderboard button (which is implemented outside of Unity.UI), scans top scores, then closes it.
Developer: In your UIController:

void OnLeaderboardWindowOpen()
{
    KeewanoSDK.ReportWindowOpen("LeaderboardWindow");
}
 
void OnLeaderboardButtonClicked()
{
    KeewanoSDK.ReportButtonClick("LeaderboardButton");
    OpenLeaderboard();
}
 
void OnLeaderboardWindowClose()
{
    KeewanoSDK.ReportWindowClose("LeaderboardWindow");
}

Note

KeewanoSDK automatically collects button click events when using Unity.UI system. If your game uses a custom UI subsystem but not implemented as standard Unity.UI, use ReportButtonClick method

Scenario 10: Advanced Item & Goal Tracking

Player Action: The player starts Level 5 Nebula Siege, where he must collect 2 Data Cores and 1 Metal Shard to power the warp gate.

Developer: In your LevelManager relevant functions integrate this flow:

// 1. Report the beginning of the level
KeewanoSDK.ReportLevelStart(levelNumber);
 
// 2. Reset all level-constrained items so nothing carries over
Keewano.Item[] startItems = { new Keewano.Item("DataCore_lvl1", 6),
                              new Keewano.Item("DataCore_lvl2", 0),
                              new Keewano.Item("DataCore_lvl3", 0),
                              new Keewano.Item("MetalShard_lvl1", 3),
                              new Keewano.Item("MetalShard_lvl2", 0),
                              new Keewano.Item("MetalShard_lvl3", 0) };
KeewanoSDK.ReportItemsReset("LevelStartItems", startItems);
 
// 3. Set up your goals for the level (collect 2 Data Cores and 1 Metal Shard)
Keewano.Item[] goals = { new Keewano.Item("DataCore_goal_remaining", 2),
                         new Keewano.Item("MetalShard_goal_remaining", 1),
                         new Keewano.Item("DataCore_goal_completed", 0),
                         new Keewano.Item("MetalShard_goal_completed", 0) };
KeewanoSDK.ReportItemsReset("LevelStartGoals", goals);
 
// 4. When two lvl-2 Data Cores merge into one lvl-3 Data Core
Keewano.Item[] fromItems1 = { new Keewano.Item("DataCore_lvl2", 2),\n new Keewano.Item("MetalShard_lvl1", 3) };
Keewano.Item[] toItems1 = { new Keewano.Item("DataCore_lvl3", 1) };
KeewanoSDK.ReportItemsExchange("LevelMergeItems", fromItems1, toItems1);
 
// 5. When a new Metal Shard lvl-2 is acquired (e.g., dropped by an enemy)
Keewano.Item[] newItems = {  new Keewano.Item("MetalShard_lvl2", 1) };
KeewanoSDK.ReportItemsExchange("LevelDrawItem", null, newItems);
 
// 6. When two lvl-3 Data Cores are consumed toward the goal
Keewano.Item[] removedItems = { new Keewano.Item("DataCore_lvl3", 2),
                                new Keewano.Item("DataCore_goal_remaining", 1) };
Keewano.Item[] addedItems = { new Keewano.Item("DataCore_goal_completed", 1) };
KeewanoSDK.ReportItemsExchange("LevelGoalCompleted", removedItems, addedItems);
 
// 7. At the end of the attempt, report the final result
KeewanoSDK.ReportLevelWin(levelNumber);
// or
KeewanoSDK.ReportLevelLose(levelNumber);

Scenario 11: Custom Error Reporting

Player Action: A non-fatal issue occurs or domain-specific validation triggered.
Developer:

Attention

Keewano AI automatically gathers unhandled exceptions and Unity error log messages. Use the following method to log any additional handled exceptions or custom errors that may not be captured by the system.

In your errors handler:

void ErrHandler(string err)
{
    KeewanoSDK.LogError(err);
}