Skip to content
T1KTheOneKit

t1k:unity:mobile:3rd-integrate

FieldValue
Modulemobile
Version2.2.2
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

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.

Scope

Section titled “Scope”
  • 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”
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 settingsPackages/com.gdk.3rd/Configs/Ads/AdSettings.cs + asset under Assets/Resources/

Workflow (Full Automation)

Section titled “Workflow (Full Automation)”

  1. Pre-flight (MANDATORY):

    • 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.
    • If spec is an xlsx/csv: detect strikethrough cells and SKIP them. For xlsx use openpyxl cell.font.strike; CSV exports lose formatting so always parse the source xlsx. A strikethrough value means “deprecated / do not integrate” — never write it to any asset, even if the value is non-empty.

  2. Identify integration class — Ads / Analytics / Mediation / IAP / RemoteConfig. Route to the matching section below.

  3. Ads integration: a. Packages/manifest.json — adapter usually ships inside com.gdk.3rd, no add needed. If a separate UPM package (e.g. com.applovin.max), add via Edit. b. Scripting define — add the network’s symbol (e.g. CLOUDX, INMOBI_SDK, IRONSOURCE_AD_QUALITY) to ProjectSettings/ProjectSettings.asset → scriptingDefineSymbols per platform. See references/scripting-defines.md. c. Settings asset — locate the AdSettings ScriptableObject (search Assets/Resources/ for AdSettings.asset or similar). Patch the sub-object for the 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. link.xml — add <assembly fullname="..." preserve="all" /> for adapter assemblies. See references/link-xml-snippets.md. e. Skip VContainer code edits — the adapter’s *VContainer.cs is gated by versionDefines and auto-registers when the define is added.

  4. Analytics integration: a. Add scripting define (e.g. ADJUST, APPSFLYER). b. Locate analytics settings asset (per-SDK: AdjustSettings.asset, AppsflyerSettings.asset). Set app token / dev key / API key / sender id. Some require iOS/Android pairs. c. link.xml — preserve 3rd.ServiceImplementation.<Sdk> and <SdkName>Tracker. d. Trackers register via the IAnalyticServices aggregator using versionDefines — no manual code wiring needed.

  5. Mediation (AppLovin MAX / Admob mediation): a. Ensure mediation root SDK installed first (AppLovin MAX or Google Mobile Ads). b. For each waterfall adapter: enable its scripting define AND populate any per-adapter SDK key (e.g. BidMachine needs bmSourceId). 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>).

Gotchas

Section titled “Gotchas”
  • Strikethrough = skip. A value with strikethrough formatting in the spec sheet is explicitly disabled by ops. Read the formatting (openpyxl cell.font.strike), not just the value. 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. Existing entries to model after: 3rd.ServiceImplementation.Ads, 3rd.ServiceImplementation.Adjust, 3rd.ServiceImplementation.Appsflyer.
  • Scripting define is the master switch. *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. If integration “doesn’t run”, check the define first.
  • Secrets MUST NOT be committed. GoogleService-Info.plist, google-services.json, Firebase keys, signing keystores — block staging via secret-guard hook. Prompt user to place in gitignored locations.
  • AppLovin MAX adapter chain. Adding AppLovin alone doesn’t enable BidMachine/IronSource as waterfall — each bidder needs its own define + Settings entry + (sometimes) a separate UPM adapter package.
  • 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.
  • 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.

References

Section titled “References”
  • references/network-id-keys.md — per-network required ID fields, Settings asset shape, example YAML patches
  • 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

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, keystores, .env). Direct user to secure storage.
  • Refuse: modifying Packages/com.gdk.3rd/ source — submodule is read-only from this skill.