MocaLib v2 API Reference

MocaLib v2 is a Unity 6 modular SDK wrapper library by Titipi Games.

Each module wraps a third-party SDK behind a consistent, async-first interface. Modules are individually enabled via scripting define symbols (MOCALIB_USE_<MODULE>), so only the modules you need are compiled into your build.

Installation

Add MocaLib to your project via the Unity Package Manager. Open Packages/manifest.json and add the entry under "dependencies":

{
  "dependencies": {
    "com.titipi.mocalib": "git://github.com/TITIPI-GAMES/unity-mocalib-v2.git?path=Assets/Titipi/MocaLib#main",
    ...
  }
}

To pin to a specific release, replace #main with a tag or commit hash, e.g. #v26.7.2.

Enable modules

After importing, open Edit → Project Settings → Player → Other Settings → Scripting Define Symbols and add the defines for the modules you need (see the table below). Modules with always on in the Define column require no symbol.

Modules

Module Define Description
AdjustModule MOCALIB_USE_ADJUST_MODULE Adjust — Attribution, events, ad revenue, purchase validation
AppLovinModule MOCALIB_USE_APPLOVIN_MODULE AppLovin MAX — App Open, Banner, Interstitial, Rewarded
AppsFlyerModule MOCALIB_USE_APPSFLYER_MODULE AppsFlyer — Attribution, events, ad revenue, purchase validation
ByteBrewModule MOCALIB_USE_BYTEBREW_MODULE ByteBrew — Custom events, user properties, purchases
CommonModule (always on) iOS ATT request; call before any SDK init
FacebookModule MOCALIB_USE_FACEBOOK_MODULE Facebook SDK init and app activation
FirebaseInAppMessagingModule MOCALIB_USE_FIREBASEINAPMESSAGING_MODULE Firebase — Native FIAM campaigns with local media caching
FirebaseModule MOCALIB_USE_FIREBASE_MODULE Firebase — Analytics, Crashlytics, Remote Config, Push
GameAnalyticsModule MOCALIB_USE_GAMEANALYTICS_MODULE GameAnalytics — Design events, resource economy tracking
IAPModule MOCALIB_USE_IAP_MODULE Unity IAP v5 purchase flow (event-driven StoreController) with optional server validation
LeaderboardModule MOCALIB_USE_FIREBASE_LEADERBOARD_MODULE Firestore leaderboards with server-side rank calculation
NetworkModule (always on) On-demand connectivity check and background polling
PlayerProfileModule MOCALIB_USE_FIREBASE_LEADERBOARD_MODULE Firestore-backed player profile with anonymous auth
RatingModule MOCALIB_USE_RATING_MODULE Native in-app review / store rating prompt
ServerTimeModule MOCALIB_USE_SERVERTIME_MODULE Authoritative UTC time from Titipi server
UtilityModule (always on) Logging helpers, platform info, version, locale, IAP receipt parsing

Initialization Order

// 1. iOS ATT — must be first, before any SDK reads IDFA
CommonModule.RequestATTracking();

// 2. Firebase — analytics, crashlytics, remote config, push; also a prerequisite
//    for LeaderboardModule, PlayerProfileModule, and FirebaseInAppMessagingModule
await FirebaseModule.InitializeAsync(firebaseConfig);

// 3. Attribution SDKs — AppsFlyer and Adjust must follow Firebase so they can
//    share the Firebase instance ID. Start all concurrently then await each.
var fbInit = FacebookModule.InitializeAsync();
var afInit = AppsFlyerModule.InitializeAsync(appsFlyerConfig);
var adjInit = AdjustModule.InitializeAsync(adjustConfig);
await fbInit; await afInit; await adjInit;

// 4. AppLovin MAX (pass Firebase instance ID as user ID for cross-platform LTV)
appLovinConfig.UserId = await FirebaseModule.GetAnalyticsInstanceIdAsync();
await AppLovinModule.InitializeAsync(appLovinConfig);

// 5. Wire cross-module events (ad revenue → analytics, IAP → attribution)
WireEvents();

// 6. Unity IAP — after AppLovin so ad suppression is in place
await IAPModule.InitializeAsync(iapConfig, products);

// 7. Remaining SDKs (order-independent)
await ByteBrewModule.InitializeAsync();
await GameAnalyticsModule.InitializeAsync();
await RatingModule.InitializeAsync(ratingConfig);
await NetworkModule.InitializeAsync();
NetworkModule.Enable(checkInterval: 15f, timeout: 5);
await ServerTimeModule.InitializeAsync();
await LeaderboardModule.InitializeAsync();   // requires Firebase
await PlayerProfileModule.InitializeAsync(); // requires Firebase

Sample App

You can clone the full repo to have a working Unity Sample App that demonstrates how to use all the modules. The sample source code is placed in the Assets/_Game/Scripts folder.

A note about Async vs Callbacks

MocaLib is async-first: methods that complete once return Awaitable or Awaitable<T>. Methods that notify you of repeating events use callbacks or C# event. Knowing which pattern to reach for makes integration code simpler.

Async — "wait for one result"

Use async/await when an operation completes exactly once and the caller needs the result to proceed.

// Sequential steps read top-to-bottom — natural and easy to follow
bool rewarded = await AppLovinModule.ShowRewardedAdAsync();
if (rewarded) GiveCoins(50);

// Error handling works with plain try/catch
try
{
    var product = await IAPModule.PurchaseProductAsync("com.example.coins");
    UnlockContent(product);
}
catch (Exception e) { ShowError(e.Message); }

// Run independent operations concurrently, then collect results
var afInit  = AppsFlyerModule.InitializeAsync(config);
var adjInit = AdjustModule.InitializeAsync(config);
await afInit;
await adjInit;

Async shines when you chain several operations — no nested callbacks, no "callback hell":

// Hard to read as callbacks; trivial as async
await ShowIntroAnimationAsync();
await Awaitable.WaitForSecondsAsync(1f);
await SpawnEnemiesAsync();
StartGameplay();

Callbacks / Events — "notify me whenever"

Use callbacks or C# events for things that can happen zero, one, or many times — subscribing once and staying subscribed.

// Module-level events: wire once, receive every occurrence
IAPModule.OnPurchaseSucceeded += (product, receipt) =>
    AppsFlyerModule.LogPurchase(product, receipt);

AppLovinModule.OnAdRevenuePaid += data =>
    FirebaseModule.LogAdRevenue(data, "AppLovin");

// Optional outcome callbacks on longer-lived operations
FirebaseModule.RegisterForPushNotifications(
    onGranted: () => ShowPushEnabledBadge(),
    onDenied:  () => ShowPushHint()
);

Quick reference

Pattern Use when… MocaLib examples
await Operation completes once; caller needs the result to continue InitializeAsync, ShowRewardedAdAsync, PurchaseProductAsync, SaveProfileAsync
Callback / event Event fires repeatedly or you need multiple subscribers OnPurchaseSucceeded, OnAdRevenuePaid, RegisterForPushNotifications

Rule of thumb: "I need a result" → async. "Tell me every time this happens" → callback or event.

Edit this page