t1k:unity:mobile:oppo-release
| Field | Value |
|---|---|
| Module | mobile |
| Version | 3.65.6 |
| Effort | medium |
| Tools | — |
Keywords: app copyright review, empty signature package, jmgame, keystore password, oppo, oppo global, oppo release, oppo sign, oppo store, oppo verification, OppoSignVerify, storepasswd
How to invoke
Section titled “How to invoke”/t1k:unity:mobile:oppo-release[flow|sign|monetization|integration|checklist]T1K: OPPO Release via JMGame
Section titled “T1K: OPPO Release via JMGame”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).
Decision Tree
Section titled “Decision Tree”| Intent | Path |
|---|---|
| “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 |
Keystore password: do this first
Section titled “Keystore password: do this first”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.
git fetch origin, thengit status --short: the tree must be clean; if not, stop and report (never stash).- Branch exists (
git branch --list oppo,git ls-remote --heads origin oppo):git switch oppo, thengit pull --rebase. Otherwise create it from the game’s default branch:git switch -c oppo origin/<default>(developormain; readgit symbolic-ref refs/remotes/origin/HEAD, never assume). - Confirm with
git rev-parse --abbrev-ref HEADthat it printsoppo, and say so, before Phases 2-3 touch a file. Phases 2-3 commit only tooppoand never merge it back; keep it rebased on the default branch (git pull --rebase origin <default>) so the Google build stays untouched. Run git throught1k-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 onoppoinstead. Phase 1 (signing) changes no project file and needs no branch.
Phase 1: OPPO Console App Verification
Section titled “Phase 1: OPPO Console App Verification”Do first: OPPO reviews ownership in 1-2 working days while the rest proceeds. Ownership is proven by the signing key.
- 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. - 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_STOREPASSits new password.) Output is<name>_signed.apkbeside the input. Exit codes and flags:references/sign-apk.md. - Compare
certSha1/certSha256with Play Console (Test and release, App signing; with Play App Signing the upload key certificate). Mismatch: stop, find the right keystore.
Phase 2: Monetization
Section titled “Phase 2: Monetization”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.
Phase 3: Integration and Handoff
Section titled “Phase 3: Integration and Handoff”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.
Jenkins QA run
Section titled “Jenkins QA run”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.
Guided flow
Section titled “Guided flow”Run order for a UITemplate-based game, notifying the human at the milestones. Detail, inputs and traps: references/guided-flow.md.
- Set the keystore password on a working copy (the human runs
keytool -storepasswdin their own terminal; verify; the original is untouched); notify when done. - Sign the empty APK from a folder holding it and that working copy (password via
--pass-file, never chat); notify when done. - Create and check out
oppo(Phase 0). - Check out the
oppobranches of theAssets/UITemplateandPackages/com.gdk.3rdsubmodules, bump both gitlinks in one commit, then verify (references/guided-flow.md§ Step 4). - 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>(theEditoralias,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. - Fix every Console compile error.
- Route banner, interstitial and rewarded calls to the JM SDK through the UITemplate ad bridge: the game writes one
XGameAdBridgein 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 withoutBridgedAdServiceWrapper(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 onoppobefore the AAR build (references/guided-flow.md§ Step 9b). - XGameUnityTool window > Publish > Import package config >
Google_XMY_SDK.asset; notify when finished. - 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’sbuildaar.batcannot 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 docThen ZIP + AAR; JMGame packages, sets up ad ID and mediation, submitsHard Rules
Section titled “Hard Rules”- 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.
Executed by
Section titled “Executed by”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.
| Step | Agent |
|---|---|
| compare fingerprint, return the signed APK, IAP choice | the main session (needs the human) |
| sign, verify, print fingerprints | the main session running scripts/oppo-sign.cjs |
| SDK removal and JMGame SDK code edits | the Unity specialist named by t1k-unity-base-agent-domain-routing |
Hard rules
Section titled “Hard rules”- 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(orCS0234 'CreateEditor' does not exist in the namespace 'Editor') after importing the SDK is a game-definednamespace Editorclashing with the SDK’s bareEditor:bun scripts/xgame-editor-alias.cjs --project <UnityProjectDir>addsusing Editor = UnityEditor.Editor;insidenamespace XGame(idempotent; re-run after every SDK re-import), thent1k unity recompile. Exit 4 means a file has nonamespace XGame {anchor: read it, do not force it.Couldn't decompress packageafter importing the SDK is known (Windows paths on Linux):references/guided-flow.md§ Step 7. It is fixed bybun scripts/xgame-linux-patch.cjs --project <UnityProjectDir>(idempotent; re-run after every SDK re-import), thent1k unity recompileand retry the import.- A newer JM SDK deletes
Assets/Plugins/Sirenixon 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.AdBridgeon a QA APK is R8 stripping the JM SDK: add its two keep rules toproguard-user.txtin the SDK-import step (references/guided-flow.md§ Step 7: expected errors).- Keystore type decides the commands:
-keypasswdfails on PKCS12 (UnsupportedOperationException;-storepasswdalone re-encrypts the key) but is REQUIRED on JKS (-storepasswdleaves 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=truealways ends the Jenkins run as FAILURE; rebuild without it. Agit: cannot fork()at checkout is a node problem: pinPARAM_NODE_LABELto 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 fallbackJmAdServiceWrapper) 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/orscripts/oppo-sign.cjs.