Skip to content

t1k:unity:mobile:3rd-integrate

FieldValue
Modulemobile
Version3.65.6
Effortmedium
Tools—

Keywords: 3rd-integrate, ad-network, ad-unit, adjust, admob, ads, analytics, applovin, appsflyer, bidmachine, bytebrew, cloudx, facebook, firebase, integrate, ironsource, link-xml, max, mediation, mmp, scripting-define, sdk, topon, yandex

/t1k:unity:mobile:3rd-integrate
<network|sdk> [--ids key=val,key=val] [--platform ios|android|both]

Wire third-party SDKs from Packages/com.gdk.3rd/ (forked from The1Studio/ThirdPartyServices) into this project. Full-automation: edits manifest, scripting defines, Settings assets, link.xml.

  • In scope: Ads (12 networks), Analytics (6 SDKs), Mediation (AppLovin MAX / Admob mediation), IDs/keys, link.xml, scripting defines, DI versionDefines.
  • Out of scope: writing native plugin C# (the adapters already exist); modifying com.gdk.3rd source (it’s a submodule — file an upstream PR instead); committing secrets (GoogleService-Info.plist, etc.).
  • “integrate ” / “add ” / “wire ”
  • “set app key / sdk key / ad unit id”
  • “set up mediation waterfall”
  • “enable CLOUDX define” / “add scripting symbol”
  • “configure analytics tracker”
ItemPath
3rd-party package rootPackages/com.gdk.3rd/
Project manifestPackages/manifest.json
Scripting definesProjectSettings/ProjectSettings.asset (per-platform sections)
Project link.xmlAssets/Scripts/link.xml
Project bootstrap (VContainer)Assets/Scripts/GameLifetimeScope.cs
Ad networks (impl)Packages/com.gdk.3rd/Ads/<Network>/
Ad networks (DI)Packages/com.gdk.3rd/DI/Ads/<Network>/
Analytics SDKsPackages/com.gdk.3rd/Analytics/<Sdk>/
Aggregated Ads settings (class)Packages/com.gdk.3rd/Configs/Ads/AdSettings.cs
Aggregator settings assetAssets/Resources/GameConfigs/ThirdPartiesConfig.asset — ads under mAdvertisingSettings.m<Network> (older Assets/Resources/Configs/AdSettings.asset is stale)
  1. Pre-flight (MANDATORY):

    • Is the Unity Editor open? ls Temp/UnityLockfile. If it exists, the Editor owns every .asset in memory and WILL overwrite your YAML edits on its next save — see the Gotcha below before editing anything.
    • Confirm Packages/com.gdk.3rd/ exists and is on master (run git -C Packages/com.gdk.3rd rev-parse --abbrev-ref HEAD). If not, git fetch origin && git checkout master && git pull origin master first.
    • Confirm target adapter folder exists under Ads/<Network>/ or Analytics/<Sdk>/
    • Parse user request for IDs/keys. Missing required IDs → AskUserQuestion before any edit. See references/network-id-keys.md for what each network needs.
    • Always ask for ByteBrew’s Game ID + SDK Key, BOTH platforms (iOS pair ≠ Android pair), and confirm the google-services.json / GoogleService-Info.plist in Assets/ belong to THIS title — neither ever appears in an ads spec sheet, and a template-initialized project silently ships the previous title’s google-services files with no compile error to flag it. See references/network-id-keys.md § ByteBrew.
    • If spec is an xlsx/csv: detect strikethrough cells and SKIP them. A strikethrough value means “deprecated / do not integrate” — never write it to any asset, even if the value is non-empty. openpyxl (cell.font.strike) is the easy path but is frequently NOT installed; the dependency-free zipfile + xl/styles.xml fallback, plus the sheet-name / shared-string traps, are in references/spec-sheet-parsing.md. CSV exports lose formatting — always parse the source xlsx.
    • Reconcile the sheet’s metadata, not just its IDs — bundle ID, target OS, mediation list. A bundle-ID mismatch against ProjectSettings/ProjectSettings.asset means those IDs belong to a different app; ask rather than assume which side is stale.
    • When only filling already-integrated ad-unit-ID values (no new SDK/define/link.xml work needed): discover the config class and live asset fresh, every session, in the current repo — never assume a fixed path or field-naming convention from a prior project. Grep for IAdNetworkSettings, class .*Settings.*Ad, or AppLovin+AdMob appearing together in one C# file to find the owning class; grep Assets/**/*.asset for a content signature unique to it (e.g. mAdvertisingSettings:, enableAppLovin:) to find the live instance. If the local source’s field names disagree with network-id-keys.md / references/ad-field-map-variants.md, the local source wins.
    • Never invent, fetch, or guess a real ad ID. Only write values the user explicitly supplies. If a network’s enable-flag is currently off and the user is populating real IDs for it, ask whether to flip it on — never silently enable a network.
  2. Identify integration class — Ads / Analytics / Mediation / IAP / RemoteConfig. Route to the matching section below.

  3. Ads integration (prefer the inspector toggle — see references/sdk-install-flow.md): a. Canonical install = tick the network’s checkbox in ThirdPartiesConfig (mAdvertisingSettings.enable<Network>). Its [OnValueChanged("OnChange<Network>")] callback atomically downloads/imports the SDK (a .unitypackage for CloudX/Yandex/ByteBrew, since those are NOT UPM deps) and sets the scripting define. Do this before any manual define edit. b. Scripting define — for UPM-delivered SDKs you may add the symbol (e.g. CLOUDX, INMOBI_SDK, IRONSOURCE_AD_QUALITY) to ProjectSettings/ProjectSettings.asset → scriptingDefineSymbols per platform (references/scripting-defines.md). For .unitypackage-delivered SDKs, NEVER add the define before the SDK is imported — the adapter asmdef references the SDK assembly and will hit CS0246. Use the toggle instead. c. Settings asset — locate ThirdPartiesConfig.asset (Assets/Resources/GameConfigs/). Patch the network sub-object under mAdvertisingSettings.m<Network>: App Key, default banner/inter/rewarded ad ids (per-platform via CrossPlatformValue), custom placement dictionaries. YAML-edit cautiously — preserve fileID/guid references. Example diff in references/network-id-keys.md. d. Mirror assets (MANDATORY for AdMob + AppLovin) — ThirdPartiesConfig is NOT the only home for these values. Its Odin [OnValueChanged] callbacks reflect them into the vendor assets that actually feed the build, and a YAML edit never fires a callback:

    Edited in ThirdPartiesConfigCallbackMust ALSO be set by hand
    mAdMob.mAndroidAppId / mIOSAppIdSaveAdmobSettingAssets/GoogleMobileAds/Resources/GoogleMobileAdsSettings.asset → adMobAndroidAppId / adMobIOSAppId and Assets/MaxSdk/Resources/AppLovinSettings.asset → adMobAndroidAppId / adMobIosAppId (via AppLovinSettings.UpdateGoogleAdsId)
    mAppLovin.mSDKKey, EnableMAXAdReviewSaveApplovinSettingAssets/MaxSdk/Resources/AppLovinSettings.asset → sdkKey, qualityServiceEnabled

    GoogleMobileAdsSettings is what injects the App ID into AndroidManifest.xml, so skipping this ships the PREVIOUS title’s App ID with no error anywhere. Grep the old value across Assets/ + ProjectSettings/ afterwards and expect zero hits. e. link.xml — derive the assembly names from Packages/com.gdk.3rd/**/*.asmdef (they are TheOne.GDK.3rd.*), then add <assembly fullname="..." preserve="all" ignoreIfMissing="1" /> for each enabled adapter and its DI.* counterpart. Assets/Scripts/link.xml may be absent or an empty <linker />: populate it, never assume entries exist. See references/link-xml-snippets.md. f. Skip VContainer code edits — the adapter’s *VContainer.cs is gated by versionDefines and auto-registers when the define is set.

  4. Analytics integration: a. Add scripting define (e.g. ADJUST, APPSFLYER). b. Locate the analytics settings asset — do NOT assume a per-SDK <Sdk>Settings.asset exists. Adjust and ByteBrew are configured in the shared Assets/Resources/GameConfigs/AnalyticConfig.asset; ByteBrew ALSO needs its vendor asset (Assets/ByteBrewSDK/Resources/ByteBrewSettings.asset) and setting only one leaves the other stale. Exact field names per SDK: references/network-id-keys.md. Some require iOS/Android pairs. c. link.xml — preserve TheOne.GDK.3rd.Analytics.<Sdk>, TheOne.GDK.3rd.DI.Analytics and <SdkName>Tracker (names from the asmdefs). d. Trackers register via the IAnalyticServices aggregator using versionDefines — no manual code wiring needed. e. Meta/Facebook diverges from (a)-(b) entirely. Fires when BOTH the project has no Assets/FacebookSDK/ AND the spec sheet supplies a Meta App ID + Client Token — then install without being asked (if Assets/FacebookSDK/ already exists, skip the import and just set the two values). Resolve the LATEST release of https://github.com/facebook/facebook-sdk-for-unity via the GitHub releases API at integration time — never hardcode a version (sdk-version-18.1.0 was latest as of 2026-09-07, cited as a reference point only). Import its .unitypackage (same delivery class as CloudX/Yandex/ByteBrew — NOT UPM, despite com.facebook.sdk appearing in the upm.the1studio.org scope list), but import it SELECTIVELY: of its 162 entries only the 48 under SDK/Plugins + link.xml are the SDK, and a full import overwrites an existing Assets/Editor/DisableBitcode.cs and shadows Packages/com.unity.ugui/. Never install the bundled EDM4U (Assets/ExternalDependencyManager/**) — MAX and AdMob already pull a newer one via UPM, and two copies is a duplicate-DLL break. Then run Facebook > Edit Settings to CREATE FacebookSettings.asset — it does not exist until that menu runs, and writing to it beforehand silently does nothing — and only then set both values on it; com.gdk.3rd ships no config asset for Facebook. Full detail: references/network-id-keys.md.

  5. Mediation (AppLovin MAX / Admob mediation): a. Ensure mediation root SDK installed first (AppLovin MAX or Google Mobile Ads). b. MAX waterfall adapters are UPM packages, not scripting defines — they install via manifest.json (com.applovin.mediation.adapters.<vendor>.android/.ios, always a pair) and MAX discovers them itself; no define, no DI wiring. Resolve the ops sheet’s brand names to vendor package names FIRST (Meta=facebook, Pangle=bytedance, Liftoff=vungle, DT Exchange=fyber, VK=mytarget, Admob=google and googleadmanager) or you will “find” networks missing that are already installed — full table + audit script + the 4-layer removal procedure: references/max-mediation-adapters.md. A sheet naming Admob on a MAX waterfall means FOUR manifest entries, not two — the googleadmanager pair ships alongside google, pinned to the SAME version per platform, even when the sheet never says “Google Ad Manager”. Only a few adapters need a per-adapter key in the Settings asset (e.g. BidMachine sellerId); googleadmanager needs none. c. Platform manifest: each mediation partner needs SKAdNetwork entries in iOS Info.plist + AndroidManifest network configs. Cannot fully automate — emit references/platform-manifest.md checklist as a follow-up.

  6. Verify:

    • Run t1k-test --compile-only (if available) or instruct user to let Unity recompile.
    • Confirm no CS0246 (missing assembly) — usually means define missing or link.xml gap.
    • Offer to commit via /t1k:git cm with message chore(3rd): integrate <network> (<keys>).
  • The Unity Editor is the authority on .asset files, not your text edit. With the Editor open (Temp/UnityLockfile present) it holds the ScriptableObject in memory and re-serializes it on its next save, silently reverting YAML you wrote. Observed: an App ID edit reverted ~5 min later, with every other field in the same file surviving — so a spot-check of one field proves nothing. Either close the Editor, or edit, focus the Editor to force the reimport, then re-grep the file and re-apply what was lost. stat -c %y <asset> tells you whether the Editor has re-saved since.
  • A committed .asset can be STALE against the current package classes, and reimport silently migrates it. Two shapes, both seen on one file: (a) fields for networks the current AdSettings.cs no longer declares (IronSource, Yandex, TopOn, BidMachine, ImmersiveAds) are dropped; (b) SerializableDictionary in com.theone.extensions changed from parallel keys:/values: lists to a single values: List<KeyValuePair> with [field: SerializeReference], so every old-format custom-placement dictionary deserializes EMPTY. Before treating that as data loss, check what the entries held — placement dicts are frequently every-value-equals-the-default redundancy, and AdPlacementHelper.FindIdForPlacement falls back to the default unit on a miss, so an empty dict changes nothing. Read the class before trusting the asset’s shape.
  • Removing an ad network is a FOUR-layer operation. Dropping the UPM package leaves the adapter in the APK via EDM4U’s committed generated files. Full procedure + the empty-maven {} trap: references/max-mediation-adapters.md.
  • Resolve brand names before declaring an adapter missing. Meta=facebook, Pangle=bytedance, Liftoff=vungle, DT Exchange=fyber, VK=mytarget, Admob=google. A sheet listing 20 networks can be 100% satisfied by a manifest that appears to name none of them. Table: references/max-mediation-adapters.md.
  • Admob on a MAX waterfall is FOUR packages, not two. com.applovin.mediation.adapters.google.* alone is a silent half-install — AppLovin splits Google demand across google and googleadmanager, so the GAM line items simply never fill. Nothing fails to compile and nothing errors at runtime, which is exactly why it survives review. Install both pairs whenever the sheet names Admob or Google Ad Manager, pin googleadmanager to its google sibling’s version per platform (both wrap one Google Mobile Ads SDK; skewing them is a duplicate-SDK conflict), and do not infer it from ad-unit-id shape — the waterfall lives in the AppLovin dashboard, which this skill cannot read. references/max-mediation-adapters.md.
  • Strikethrough = skip. A value with strikethrough formatting in the spec sheet is explicitly disabled by ops. Read the formatting, not just the value; openpyxl is often unavailable, so use the dependency-free parser in references/spec-sheet-parsing.md. CSV exports lose this signal — always parse the source xlsx.
  • Per-platform IDs are NOT interchangeable. iOS App Key ≠ Android App Key. The Settings assets use CrossPlatformValue { iOS, Android } — always set both when integrating cross-platform.
  • link.xml is load-bearing. IL2CPP strips any assembly not preserved → runtime TypeLoadException or silent no-op. After adding an adapter, ALWAYS update link.xml. Derive entries from the TheOne.GDK.3rd.* asmdef names; the file may start empty.
  • Define gates compilation, but it is not the install step. *VContainer.cs and Tracker.cs files are #if <DEFINE> gated — without the define the adapter compiles to nothing → no DI binding → silent fallback to Dummy. But for .unitypackage-delivered SDKs (CloudX, Yandex, ByteBrew) the define alone is insufficient AND harmful if set first: the adapter asmdef references the SDK assembly, so setting the define before importing the .unitypackage throws CS0246. The inspector OnChange<Network> toggle imports the SDK and sets the define together — prefer it. See references/sdk-install-flow.md.
  • Secrets MUST NOT be committed. GoogleService-Info.plist, google-services.json, Firebase keys, keystore passwords — block staging via secret-guard hook. Prompt user to place in gitignored locations. The per-game signing keystore is the one committed exception (studio decision, see t1k-unity-mobile-keystore-create).
  • AppLovin MAX adapter chain. Adding the MAX SDK alone does not give you a waterfall — each bidder needs its own UPM adapter pair in manifest.json. It does NOT need a scripting define or DI wiring; MAX discovers installed adapters itself. A handful additionally need a key in the Settings asset (e.g. BidMachine sellerId). Enabling the network in the MAX dashboard is a separate, ops-side step this skill cannot do.
  • Attribution callback ordering. Adjust and AppsFlyer must initialize BEFORE the first ad impression for correct attribution. Their *Tracker.cs registers in the bootstrap scope — do NOT move to gameplay scope.
  • IAnalyticServices aggregator pattern. Trackers don’t replace each other; they all fire in parallel. New tracker = additive entry in the aggregator, gated by define.
  • Editor-only attributes — [LabelText], [BoxGroup] are Sirenix Odin. Don’t touch them when YAML-editing settings.
  • Unity YAML is NOT generic YAML. A .asset file uses %YAML 1.1 + %TAG !u! + a !u!114 &<fileID> object header with exact key ordering and indentation. Never parse/round-trip it through a generic YAML library (js-yaml, PyYAML, etc.) — that mangles the !u!114 tag and can reorder keys, corrupting the asset in the Editor. Apply a targeted line-level edit instead: find the exact line for the nested field path (matching indentation), replace only the value after : , leave every other line untouched. Adding a new backfill/custom-placement entry means appending a correctly-indented new block, not overwriting an existing scalar. Re-read the affected region after editing and show the user a before/after diff of just the changed lines.
  • Some vendored versions use an m-prefixed serialized-field naming convention (mSDKKey, mIosId/mAndroidId) instead of the plain property names in network-id-keys.md — see references/ad-field-map-variants.md for that shape, including backfill-array and parallel keys[]/values[] dict conventions.
  • Submodule edits. Never modify files inside Packages/com.gdk.3rd/ for integration — those are upstream. If a missing adapter blocks integration, surface a follow-up /t1k:issue against The1Studio/ThirdPartyServices.
  • Facebook define is X_FACEBOOK_SDK, not FACEBOOK_SDK (THEONE_FACEBOOK_SDK is the pre-rename spelling) — verified against Packages/com.gdk.3rd/Analytics/Facebook/FacebookSDKService.cs. It ships as a .unitypackage from facebook/facebook-sdk-for-unity GitHub releases (resolve latest at integration time, don’t pin), not UPM — same “define after import, never before” ordering as CloudX/Yandex/ByteBrew. com.gdk.3rd has no Facebook config asset; App ID + Client Token live only in the vendor’s own FacebookSettings.asset, which Facebook > Edit Settings must create first (it is not shipped in the package), and whose appIds/clientTokens fields are LISTS in recent SDK versions — never write a bare string. Import the package selectively (48 of 162 entries); a full import clobbers project files, and its bundled EDM4U must be excluded because the project already has a newer one via UPM. Details: references/network-id-keys.md.
  • references/sdk-install-flow.md — inspector OnChange<Network> toggle install (.unitypackage download + define), ThirdPartiesConfig asset shape; why not to pre-add the define
  • references/spec-sheet-parsing.md — reading an ops .xlsx: strikethrough detection without openpyxl, sheet/shared-string traps
  • references/max-mediation-adapters.md — brand↔package name map, the Admob→four-package rule, install audit, the 4-layer removal procedure
  • references/network-id-keys.md — per-network required ID fields, Settings asset shape, example YAML patches
  • references/ad-field-map-variants.md — on-disk YAML field shapes for the m-prefixed serialized-field naming variant (SDK keys, per-platform ad IDs, backfill arrays, custom-placement dicts), when it differs from network-id-keys.md
  • references/scripting-defines.md — canonical define symbols + how to edit ProjectSettings.asset
  • references/link-xml-snippets.md — copy-paste assembly entries per adapter
  • references/platform-manifest.md — iOS SKAdNetwork + Android manifest checklist per network
  • Never echo full app keys / SDK keys back to the user in tool output beyond the last 4 chars.
  • Refuse: requests to commit secret files (Firebase plist, keystore passwords, .env). Direct user to secure storage. A per-game .keystore is committed by design; refuse only its password.
  • Refuse: modifying Packages/com.gdk.3rd/ source — submodule is read-only from this skill.