t1k:unity:mobile:3rd-integrate
| Field | Value |
|---|---|
| Module | mobile |
| Version | 3.65.6 |
| Effort | medium |
| 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
How to invoke
Section titled “How to invoke”/t1k:unity:mobile:3rd-integrate<network|sdk> [--ids key=val,key=val] [--platform ios|android|both]T1K — 3rd-Party Integration
Section titled “T1K — 3rd-Party Integration”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.).
When to Use
Section titled “When to Use”- “integrate
” / “add ” / “wire ” - “set
app key / sdk key / ad unit id” - “set up mediation waterfall”
- “enable CLOUDX define” / “add scripting symbol”
- “configure analytics tracker”
Project Constants
Section titled “Project Constants”| Item | Path |
|---|---|
| 3rd-party package root | Packages/com.gdk.3rd/ |
| Project manifest | Packages/manifest.json |
| Scripting defines | ProjectSettings/ProjectSettings.asset (per-platform sections) |
| Project link.xml | Assets/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 SDKs | Packages/com.gdk.3rd/Analytics/<Sdk>/ |
| Aggregated Ads settings (class) | Packages/com.gdk.3rd/Configs/Ads/AdSettings.cs |
| Aggregator settings asset | Assets/Resources/GameConfigs/ThirdPartiesConfig.asset — ads under mAdvertisingSettings.m<Network> (older Assets/Resources/Configs/AdSettings.asset is stale) |
Workflow (Full Automation)
Section titled “Workflow (Full Automation)”-
Pre-flight (MANDATORY):
- Is the Unity Editor open?
ls Temp/UnityLockfile. If it exists, the Editor owns every.assetin 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 onmaster(rungit -C Packages/com.gdk.3rd rev-parse --abbrev-ref HEAD). If not,git fetch origin && git checkout master && git pull origin masterfirst. - Confirm target adapter folder exists under
Ads/<Network>/orAnalytics/<Sdk>/ - Parse user request for IDs/keys. Missing required IDs → AskUserQuestion before any edit. See
references/network-id-keys.mdfor 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.plistinAssets/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. Seereferences/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-freezipfile+xl/styles.xmlfallback, plus the sheet-name / shared-string traps, are inreferences/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.assetmeans 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, orAppLovin+AdMobappearing together in one C# file to find the owning class; grepAssets/**/*.assetfor a content signature unique to it (e.g.mAdvertisingSettings:,enableAppLovin:) to find the live instance. If the local source’s field names disagree withnetwork-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.
- Is the Unity Editor open?
-
Identify integration class — Ads / Analytics / Mediation / IAP / RemoteConfig. Route to the matching section below.
-
Ads integration (prefer the inspector toggle — see
references/sdk-install-flow.md): a. Canonical install = tick the network’s checkbox inThirdPartiesConfig(mAdvertisingSettings.enable<Network>). Its[OnValueChanged("OnChange<Network>")]callback atomically downloads/imports the SDK (a.unitypackagefor 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) toProjectSettings/ProjectSettings.asset→scriptingDefineSymbolsper 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 — locateThirdPartiesConfig.asset(Assets/Resources/GameConfigs/). Patch the network sub-object undermAdvertisingSettings.m<Network>: App Key, default banner/inter/rewarded ad ids (per-platform viaCrossPlatformValue), custom placement dictionaries. YAML-edit cautiously — preservefileID/guidreferences. Example diff inreferences/network-id-keys.md. d. Mirror assets (MANDATORY for AdMob + AppLovin) —ThirdPartiesConfigis 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 ThirdPartiesConfigCallback Must ALSO be set by hand mAdMob.mAndroidAppId/mIOSAppIdSaveAdmobSettingAssets/GoogleMobileAds/Resources/GoogleMobileAdsSettings.asset→adMobAndroidAppId/adMobIOSAppIdandAssets/MaxSdk/Resources/AppLovinSettings.asset→adMobAndroidAppId/adMobIosAppId(viaAppLovinSettings.UpdateGoogleAdsId)mAppLovin.mSDKKey,EnableMAXAdReviewSaveApplovinSettingAssets/MaxSdk/Resources/AppLovinSettings.asset→sdkKey,qualityServiceEnabledGoogleMobileAdsSettingsis what injects the App ID intoAndroidManifest.xml, so skipping this ships the PREVIOUS title’s App ID with no error anywhere. Grep the old value acrossAssets/+ProjectSettings/afterwards and expect zero hits. e. link.xml — derive the assembly names fromPackages/com.gdk.3rd/**/*.asmdef(they areTheOne.GDK.3rd.*), then add<assembly fullname="..." preserve="all" ignoreIfMissing="1" />for each enabled adapter and itsDI.*counterpart.Assets/Scripts/link.xmlmay be absent or an empty<linker />: populate it, never assume entries exist. Seereferences/link-xml-snippets.md. f. Skip VContainer code edits — the adapter’s*VContainer.csis gated byversionDefinesand auto-registers when the define is set. -
Analytics integration: a. Add scripting define (e.g.
ADJUST,APPSFLYER). b. Locate the analytics settings asset — do NOT assume a per-SDK<Sdk>Settings.assetexists. Adjust and ByteBrew are configured in the sharedAssets/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 — preserveTheOne.GDK.3rd.Analytics.<Sdk>,TheOne.GDK.3rd.DI.Analyticsand<SdkName>Tracker(names from the asmdefs). d. Trackers register via theIAnalyticServicesaggregator usingversionDefines— no manual code wiring needed. e. Meta/Facebook diverges from (a)-(b) entirely. Fires when BOTH the project has noAssets/FacebookSDK/AND the spec sheet supplies a Meta App ID + Client Token — then install without being asked (ifAssets/FacebookSDK/already exists, skip the import and just set the two values). Resolve the LATEST release ofhttps://github.com/facebook/facebook-sdk-for-unityvia the GitHub releases API at integration time — never hardcode a version (sdk-version-18.1.0was latest as of 2026-09-07, cited as a reference point only). Import its.unitypackage(same delivery class as CloudX/Yandex/ByteBrew — NOT UPM, despitecom.facebook.sdkappearing in theupm.the1studio.orgscope list), but import it SELECTIVELY: of its 162 entries only the 48 underSDK/Plugins+link.xmlare the SDK, and a full import overwrites an existingAssets/Editor/DisableBitcode.csand shadowsPackages/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 runFacebook > Edit Settingsto CREATEFacebookSettings.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.3rdships no config asset for Facebook. Full detail:references/network-id-keys.md. -
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=googleandgoogleadmanager) 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 — thegoogleadmanagerpair ships alongsidegoogle, 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. BidMachinesellerId);googleadmanagerneeds none. c. Platform manifest: each mediation partner needs SKAdNetwork entries in iOS Info.plist + AndroidManifest network configs. Cannot fully automate — emitreferences/platform-manifest.mdchecklist as a follow-up. -
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 cmwith messagechore(3rd): integrate <network> (<keys>).
- Run
Hard rules
Section titled “Hard rules”- The Unity Editor is the authority on
.assetfiles, not your text edit. With the Editor open (Temp/UnityLockfilepresent) 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
.assetcan be STALE against the current package classes, and reimport silently migrates it. Two shapes, both seen on one file: (a) fields for networks the currentAdSettings.csno longer declares (IronSource, Yandex, TopOn, BidMachine, ImmersiveAds) are dropped; (b)SerializableDictionaryincom.theone.extensionschanged from parallelkeys:/values:lists to a singlevalues: 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, andAdPlacementHelper.FindIdForPlacementfalls 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 acrossgoogleandgoogleadmanager, 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, pingoogleadmanagerto itsgooglesibling’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.xmlis load-bearing. IL2CPP strips any assembly not preserved → runtimeTypeLoadExceptionor silent no-op. After adding an adapter, ALWAYS update link.xml. Derive entries from theTheOne.GDK.3rd.*asmdef names; the file may start empty.- Define gates compilation, but it is not the install step.
*VContainer.csandTracker.csfiles 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.unitypackagethrows CS0246. The inspectorOnChange<Network>toggle imports the SDK and sets the define together — prefer it. Seereferences/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, seet1k-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. BidMachinesellerId). 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.csregisters in the bootstrap scope — do NOT move to gameplay scope. IAnalyticServicesaggregator 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
.assetfile 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!114tag 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 innetwork-id-keys.md— seereferences/ad-field-map-variants.mdfor that shape, including backfill-array and parallelkeys[]/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:issueagainstThe1Studio/ThirdPartyServices. - Facebook define is
X_FACEBOOK_SDK, notFACEBOOK_SDK(THEONE_FACEBOOK_SDKis the pre-rename spelling) — verified againstPackages/com.gdk.3rd/Analytics/Facebook/FacebookSDKService.cs. It ships as a.unitypackagefromfacebook/facebook-sdk-for-unityGitHub releases (resolve latest at integration time, don’t pin), not UPM — same “define after import, never before” ordering as CloudX/Yandex/ByteBrew.com.gdk.3rdhas no Facebook config asset; App ID + Client Token live only in the vendor’s ownFacebookSettings.asset, whichFacebook > Edit Settingsmust create first (it is not shipped in the package), and whoseappIds/clientTokensfields 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
Section titled “References”references/sdk-install-flow.md— inspectorOnChange<Network>toggle install (.unitypackagedownload + define),ThirdPartiesConfigasset shape; why not to pre-add the definereferences/spec-sheet-parsing.md— reading an ops .xlsx: strikethrough detection without openpyxl, sheet/shared-string trapsreferences/max-mediation-adapters.md— brand↔package name map, the Admob→four-package rule, install audit, the 4-layer removal procedurereferences/network-id-keys.md— per-network required ID fields, Settings asset shape, example YAML patchesreferences/ad-field-map-variants.md— on-disk YAML field shapes for them-prefixed serialized-field naming variant (SDK keys, per-platform ad IDs, backfill arrays, custom-placement dicts), when it differs fromnetwork-id-keys.mdreferences/scripting-defines.md— canonical define symbols + how to editProjectSettings.assetreferences/link-xml-snippets.md— copy-paste assembly entries per adapterreferences/platform-manifest.md— iOS SKAdNetwork + Android manifest checklist per network
Security
Section titled “Security”- 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
.keystoreis committed by design; refuse only its password. - Refuse: modifying
Packages/com.gdk.3rd/source — submodule is read-only from this skill.