Skip to content

t1k:unity:mobile:oppo-release

FieldValue
Modulemobile
Version3.65.6
Effortmedium
Tools—

Keywords: app copyright review, empty signature package, jmgame, keystore password, oppo, oppo global, oppo release, oppo sign, oppo store, oppo verification, OppoSignVerify, storepasswd

/t1k:unity:mobile:oppo-release
[flow|sign|monetization|integration|checklist]

Producer-side work to publish a Unity game on OPPO Store with JMGame as publisher. Source of truth is JMGame’s checklist sheet (Vietnamese tab; the English tab differs, see references/integration-handoff.md § Sheet drift) and OPPO doc #12. Re-read the sheet before a new game: JMGame edits it.

  • In scope: setting the keystore password on a working copy (first step), signing the empty verification APK, ad and IAP setup for the OPPO build, the files handed to JMGame, the ordered checklist.
  • Out of scope: packaging the OPPO build (JMGame does it), the OPPO console upload and store submission (JMGame, unless the dev publishes under their own OPPO account), creating a keystore (t1k-unity-mobile-keystore-create), general SDK installs (t1k-unity-mobile-3rd-integrate), Firebase Remote Config deploys (t1k-unity-mobile-remote-config-deploy).
IntentPath
“Do the whole OPPO release / run the flow”Guided flow → references/guided-flow.md
“Change the keystore / key password, prepare the keystore”Keystore password → references/sign-apk.md
“Start OPPO work / prepare the project”Phase 0
“Sign the OPPO empty APK / verification”Phase 1 → references/sign-apk.md
“Ads / IAP for the OPPO build”Phase 2 → references/monetization.md
“SDK, ZIP, event-tracking doc”Phase 3 → references/integration-handoff.md
“Build the AAR”The Jenkins QA run (Jenkinsfile/XGameAndroid) builds it with the QA APK: references/oppo-jenkins-job.md. Local fallback (Linux; the SDK’s own step is Windows-only; headless --export with the Editor closed, or after Publish): scripts/build-aar.sh → references/build-aar-linux.md
“Create or migrate the OPPO Jenkins QA job for the oppo branch” (QA APK + AAR)references/oppo-jenkins-job.md § “Pipeline and migration”
“What is left to do?”Order, then ask which step is done

Before Phase 0 and before signing: make a working copy of the game’s Google keystore outside the repo and set its store and key password to the keystore name (<name>.keystore gets password <name>). The original keeps its password, the alias stays as it is, and the certificate (SHA-1/SHA-256) does not change, so OPPO and Play need no re-verification. The human runs the keytool commands in their own terminal (hidden prompt, never chat): -storepasswd alone for a PKCS12 keystore (one password for store and key, -keypasswd unsupported), -storepasswd then -keypasswd for a JKS one (check the type with file <ks> first). Then verify four things: new password opens, key opens, old password rejected, fingerprints equal the original’s. Commands and checks: references/sign-apk.md § “Set the keystore password first”. Phase 1 then signs with that copy.

Phase 0: Create the oppo branch (before ANY change to the game project)

Section titled “Phase 0: Create the oppo branch (before ANY change to the game project)”

The OPPO build removes SDKs, hides IAP and adds the JMGame SDK, so it never lands on the main line. Work on its own branch.

  1. git fetch origin, then git status --short: the tree must be clean; if not, stop and report (never stash).
  2. Branch exists (git branch --list oppo, git ls-remote --heads origin oppo): git switch oppo, then git pull --rebase. Otherwise create it from the game’s default branch: git switch -c oppo origin/<default> (develop or main; read git symbolic-ref refs/remotes/origin/HEAD, never assume).
  3. Confirm with git rev-parse --abbrev-ref HEAD that it prints oppo, and say so, before Phases 2-3 touch a file. Phases 2-3 commit only to oppo and never merge it back; keep it rebased on the default branch (git pull --rebase origin <default>) so the Google build stays untouched. Run git through t1k-git-manager (rules/orchestration-rules.md). A session pinned to a lane worktree must not switch its own HEAD: brief a sub-agent into a caller-created worktree on oppo instead. Phase 1 (signing) changes no project file and needs no branch.

Do first: OPPO reviews ownership in 1-2 working days while the rest proceeds. Ownership is proven by the signing key.

  1. The marketing team sends the empty signature APK (OppoSignVerify.apk, downloaded from OPPO’s app copyright review page, doc #12). If they ask, give them the game’s app name and package name (the Google Play build’s; no stray spaces). JMGame is not involved in this phase.
  2. Sign it with the Google build’s key: OPPO_SIGN_STOREPASS=... bun .claude/skills/t1k-unity-mobile-oppo-release/scripts/oppo-sign.cjs --apk <OppoSignVerify.apk> --keystore <ks> --alias <alias> (<ks> is the working copy from the keystore-password step, OPPO_SIGN_STOREPASS its new password.) Output is <name>_signed.apk beside the input. Exit codes and flags: references/sign-apk.md.
  3. Compare certSha1/certSha256 with Play Console (Test and release, App signing; with Play App Signing the upload key certificate). Mismatch: stop, find the right keystore.

Ad formats: interstitial (shown when a screen/popup opens, with a per-placement JSON delay in Remote Config), rewarded, banner, all configurable through Firebase. IAP: hide it (recommended), disable it with a message, or keep it behind a third-party payment. Detail: references/monetization.md.

Get the SDK through the xgame downloader package (references/integration-handoff.md § “Where the SDK comes from”: import it on the oppo branch only, confirm the source with marketing first). Remove every other SDK, integrate the JMGame SDK, deliver the ZIP project and AAR (no build), send the event-tracking doc. Detail and links: references/integration-handoff.md.

Jenkinsfile/XGameAndroid (shared library xgame_android) builds the QA APK and the partner AAR in one run, uploads them and posts to Discord. Test ads are on by default (PARAM_XGAME_ADD_TEST_ADS). Job setup, migration, the test-ad check and the gotchas: references/oppo-jenkins-job.md. The QA APK is not a store build, and sending the Jenkins AAR is the human’s call. After an SDK upgrade, read references/oppo-jenkins-job.md § “Hard rules” (the “After an SDK upgrade” entry, JM SDK 2026.10.29.1) before the first trigger: each entry is a build that failed, then the bridge fix.

Run order for a UITemplate-based game, notifying the human at the milestones. Detail, inputs and traps: references/guided-flow.md.

  1. Set the keystore password on a working copy (the human runs keytool -storepasswd in their own terminal; verify; the original is untouched); notify when done.
  2. Sign the empty APK from a folder holding it and that working copy (password via --pass-file, never chat); notify when done.
  3. Create and check out oppo (Phase 0).
  4. Check out the oppo branches of the Assets/UITemplate and Packages/com.gdk.3rd submodules, bump both gitlinks in one commit, then verify (references/guided-flow.md § Step 4).
  5. Disable every ad/analytics SDK and Sirenix (the JM SDK ships its own), keep Firebase; ask for the local path of the JM SDK package and import it. Then, in this order and before the first Editor load: bun scripts/xgame-editor-alias.cjs --project <dir> (the Editor alias, references/guided-flow.md § Step 7), bun scripts/xgame-keep-odin.cjs --project <dir> if the game’s code uses real Odin (references/guided-flow.md § Step 7), bun scripts/xgame-linux-patch.cjs --project <dir> if still needed, open the Editor.
  6. Fix every Console compile error.
  7. Route banner, interstitial and rewarded calls to the JM SDK through the UITemplate ad bridge: the game writes one XGameAdBridge in Assembly-CSharp (the SDK has no asmdef, so game asmdef code cannot call it directly); the per-game wrapper is only the fallback for a UITemplate without BridgedAdServiceWrapper (references/guided-flow.md § Step 8). Banner: AfterLoading = every screen and popup, Manually = only the configured screens. 7b. Hide the rate-us flow if the game has one: remove its trigger and define on oppo before the AAR build (references/guided-flow.md § Step 9b).
  8. XGameUnityTool window > Publish > Import package config > Google_XMY_SDK.asset; notify when finished.
  9. Publish (XMY Google, AAR) in the Editor, then bun scripts/xgame-aar-package.cjs --project <dir> --build --android-player <AndroidPlayer dir> to build and name the AAR and its symbols zip (the SDK’s buildaar.bat cannot run on Linux/macOS); notify when finished. Detail: references/guided-flow.md § Step 10.
Day 1 Keystore password step, Phase 0 (oppo branch), then Phase 1 steps 1-3 (receive the empty APK from marketing, sign, compare fingerprint)
Meanwhile Phase 2, and Phase 3: remove SDKs, integrate JMGame SDK, tracking doc
Then ZIP + AAR; JMGame packages, sets up ad ID and mediation, submits
  • The store and key password reach the script through an env var or --pass-file, never argv, chat or a commit. Never print it.
  • Never send a keystore, private key or password to the marketing team, JMGame or OPPO: the signed APK is the only artifact.
  • Never use a keystore that is not the game’s Google build key; a project-named file in another folder is not proof. Fingerprint first.
  • Never change the game project from its default branch: Phase 0 first, and the OPPO changes stay on oppo.
  • The script never overwrites an existing output; the human moves the old file.

Signing is deterministic (scripts/oppo-sign.cjs); everything else is a checklist the human drives, so the whole skill runs inline in the main session, with the human in the loop. Not delegable.

StepAgent
compare fingerprint, return the signed APK, IAP choicethe main session (needs the human)
sign, verify, print fingerprintsthe main session running scripts/oppo-sign.cjs
SDK removal and JMGame SDK code editsthe Unity specialist named by t1k-unity-base-agent-domain-routing
  • The JM SDK has no asmdef; never edit a submodule or the SDK to work around that (SDK edits are lost on re-import). Details: references/guided-flow.md.
  • CS0118 'Editor' is a namespace (or CS0234 'CreateEditor' does not exist in the namespace 'Editor') after importing the SDK is a game-defined namespace Editor clashing with the SDK’s bare Editor: bun scripts/xgame-editor-alias.cjs --project <UnityProjectDir> adds using Editor = UnityEditor.Editor; inside namespace XGame (idempotent; re-run after every SDK re-import), then t1k unity recompile. Exit 4 means a file has no namespace XGame { anchor: read it, do not force it.
  • Couldn't decompress package after importing the SDK is known (Windows paths on Linux): references/guided-flow.md § Step 7. It is fixed by bun scripts/xgame-linux-patch.cjs --project <UnityProjectDir> (idempotent; re-run after every SDK re-import), then t1k unity recompile and retry the import.
  • A newer JM SDK deletes Assets/Plugins/Sirenix on every Editor load (InspectorPluginCleanup) and breaks game code that uses real Odin (~900 CS0246): bun scripts/xgame-keep-odin.cjs --project <dir> before the first Editor load after the import, and again after every SDK re-import (references/guided-flow.md § Step 7).
  • ClassNotFoundException: com.union.sdk.unity.helper.AdBridge on a QA APK is R8 stripping the JM SDK: add its two keep rules to proguard-user.txt in the SDK-import step (references/guided-flow.md § Step 7: expected errors).
  • Keystore type decides the commands: -keypasswd fails on PKCS12 (UnsupportedOperationException; -storepasswd alone re-encrypts the key) but is REQUIRED on JKS (-storepasswd leaves the key password unchanged). Details: references/sign-apk.md § “Set the keystore password first”.
  • Keystore passwords are not guessable and a rejected guess is not progress: stop and find the real one (keystore_pw.md, the creator, Jenkins).
  • The Jenkins console prints the keystore and alias passwords in clear (known, not fixed). Never write the value anywhere; recommend rotating it (references/oppo-jenkins-job.md § Hard rules).
  • PARAM_WIPE_OUT_WORKSPACE=true always ends the Jenkins run as FAILURE; rebuild without it. A git: cannot fork() at checkout is a node problem: pin PARAM_NODE_LABEL to another node.
  • Change the keystore password only when the store and key password is the studio default tothemoon: test it ONCE, read-only, on the working copy, with the password in an env var (keytool -list -keystore <copy> -storepass:env VAR, never argv, never the original). Accepted: set the working copy’s store and key password to the keystore name. Rejected (keystore password was incorrect): do not change anything and do not try variants; the keystore already has its own password, so ask the human for it (mode-600 file, :file) and sign with it as is. A password that already equals the keystore name also needs no change.
  • The game’s ad wrapper (BridgedAdServiceWrapper, or the fallback JmAdServiceWrapper) skips the base capping (interval, start level, remove-ads, force), so every call shows an ad, and its callback runs at once, while the ad shows: request interstitials on screen open, not per button (references/monetization.md § “Interstitial on screen open”).
  • Wrong or stale guidance here: emit a skill-bug marker for this skill; the fix lands in this file, references/ or scripts/oppo-sign.cjs.