Migrating from purchase to sdk_recharge

The SDK v2 auto-tracking feature replaces the legacy purchase event with sdk_recharge, which provides richer tracking data and automatic event handling.

What Changed

Before (Legacy)

The purchase event was manually logged and had limited data:

// Android - Manual tracking
OEGAnalytics.logPurchase(
    eventToken = "purchase",
    price = 4.99,
    currency = "USD",
    transactionId = "GPA.1234-5678",
    productId = "com.oeg.game.gem_pack"
)

// iOS - Manual tracking
OEGAnalytics.shared.logPurchase(
    eventToken: "purchase",
    price: 4.99,
    currency: "USD",
    transactionId: "TX-1234",
    productId: "com.oeg.game.gem_pack"
)

After (SDK v2)

The sdk_recharge event is automatically tracked when using OEGPayment.purchaseAndVerify() and includes additional context:

• Automatic tracking: No manual logPurchase() calls needed
• Role information: Includes role_id, role_name, server_id from setGameRole()
• First charge detection: Tracks is_first_charge flag automatically
• Richer metadata: Device info, SDK version, app version, timestamps

Migration Steps

Step 1: Update Backend Config

In the Alogame CMS, update your game's tracking configuration:

Remove:

{
  "tracking": {
    "android": {
      "event_token_mapping": {
        "purchase": "old_token_abc"
      }
    }
  }
}

Add:

{
  "tracking": {
    "android": {
      "event_token_mapping": {
        "sdk_recharge": "new_token_xyz"
      }
    }
  }
}

Do the same for the ios section.

Step 2: Remove Manual Tracking Calls (If Any)

If you were manually calling logPurchase() outside of OEGPayment.purchaseAndVerify(), remove those calls:

Android:

// ❌ Remove this
OEGAnalytics.logPurchase(...)

// ✅ Just use this - tracking is automatic
OEGPayment.purchaseAndVerify(productId, gameData) { result ->
    // Handle result
}

iOS:

// ❌ Remove this
OEGAnalytics.shared.logPurchase(...)

// ✅ Just use this - tracking is automatic
OEGPayment.shared.purchaseAndVerify(productId: productId, gameData: gameData) { result in
    // Handle result
}

Step 3: Set Game Role (Recommended)

To enrich sdk_recharge events with player context, call setGameRole() after the player enters the game:

Android:

import vn.oeg.sdk.v2.core.auth.OEGAuthCore

OEGAuthCore.setGameRole(
    serverId = "server_01",
    serverName = "Server 1",
    roleId = "character_123",
    roleName = "DragonSlayer",
    level = 50
)

iOS:

import OegSdkV2

OegSdkCore.shared.setGameRole(
    serverId: "server_01",
    serverName: "Server 1",
    roleId: "character_123",
    roleName: "DragonSlayer",
    level: 50
)

If setGameRole() is not called, the SDK will use fallback data from the IAP flow's GameData parameter.

New Event Fields

The sdk_recharge event includes these additional fields compared to purchase:

Field	Description	Source
role_id	Player character ID	setGameRole() or GameData
role_name	Player character name	setGameRole() or GameData
server_id	Game server ID	setGameRole() or GameData
is_first_charge	First purchase flag ("1" or "0")	Automatic (device-based)
account_id	User account ID	Automatic
event_id	Unique event identifier	Automatic (UUID)
recharge_time	Purchase timestamp (UTC+7)	Automatic
app_version	Host app version	Automatic
sdk_version	SDK version	Automatic
os_platform	"Android" or "iOS"	Automatic
os_version	OS version	Automatic
device_id	Device identifier	Automatic
device_name	Device model	Automatic

Backward Compatibility

• Legacy SDK games: Not affected (they don't use /v2/config)
• v2 SDK without token: Events are silently skipped (no errors)
• Gradual migration: You can keep both purchase and sdk_recharge tokens during transition

Testing

After migration, verify events appear in your Adjust dashboard:

1. Make a test purchase in your game
2. Check Adjust dashboard for sdk_recharge event
3. Verify all fields are populated correctly
4. Confirm is_first_charge is "1" for first purchase, "0" for subsequent purchases

Troubleshooting

Event not appearing in Adjust:

• Verify sdk_recharge token is configured in backend config
• Check that OEGPayment.purchaseAndVerify() is being used (not manual IAP flow)
• Ensure SDK initialization completed successfully

Missing role information:

• Call setGameRole() after player enters game
• Verify GameData parameter in purchaseAndVerify() includes fallback values

First charge always showing "0":

• Check device hasn't been used for testing before (first charge is device-based)
• Clear app data to reset first charge detection for testing

Support

For questions or issues, contact the Alogame SDK team or refer to the Analytics documentation.