Integration · Host callbacks
9 optional callback groups and their fallback behavior
Game API calls cross the runtime boundary and are dispatched to handlers implemented by the host app. All 9 groups below are optional: a game can start with none registered, and only calls that require a missing capability fail.
The “Behavior when absent” column is the runtime contract. Requests always settle: the runtime neither reports success on the host's behalf nor leaves a request pending. Only GameSessionListener must be registered, for ready, exit, and error events.
- PermissionHandler
PermissionSink
setPermissionHandler()authorize
getSetting
plus 30 permission-gated interfaces for camera, microphone, Bluetooth, location, photos, and contactsEvery scope is treated as denied. getSetting returns no true values, gated calls fail with auth deny, and authorize reports that no permission handler is registered. This is deliberate: a game never inherits permissions already granted to the host app without an explicit host decision. - AdHandler
AdEventSink
setAdHandler()createRewardedVideoAd
createInterstitialAd
createBannerAd
createCustomAd
createGridAd
createGameBanner
createGameIcon
createGamePortalAd objects remain callable, but no ad is shown. Every request settles: create, load, and show report errors; show also closes with isEnded=false; hide reports the hidden state. A game waiting for an ad therefore continues instead of hanging. The runtime never grants a reward, and isEnded is always false. Hosts that support only selected formats get the same behavior for every unsupported format. - AuthHandler
setAuthHandler()login
checkSession
getUserInfo
getPhoneNumberlogin fails with no auth handler. It neither succeeds silently nor remains pending. - PaymentHandler
PaymentSink
setPaymentHandler()checkIsSupportMidasPayment
requestMidasPayment
requestMidasPaymentGameItemcheckIsSupportMidasPayment returns allow_pay: false, so conforming content does not open a store that cannot complete a purchase. Forced requests fail with -2 not supported. The runtime holds no merchant credentials and never reports a payment as successful. - ShareHandler
ShareSink
setShareHandler()shareAppMessageThe call fails with -2 not supported rather than being dropped silently, because content may wait for sharing to complete before continuing. - NavigationHandler
NavigationSink
setNavigationHandler()navigateToMiniProgram
openCustomerServiceConversationBoth calls fail with not supported. The host decides whether a game may send the user outside the app. - SettingHandler
SettingSink
setSettingHandler()openSettingThe call fails with -2 not supported. openSetting targets the host app's permission settings, and the runtime does not open that page on the host's behalf. - SubpackageHandler
setSubpackageHandler()loadSubpackage
preDownloadSubpackageDownload requests fail. If the subpackage already exists locally, loadSubpackage falls back to the local files. When a handler is registered, the host only downloads the ZIP to a temporary path; the runtime extracts, verifies, and mounts it. - GameLogHandler
setGameLogHandler()getGameLogManagerAndroid falls back to logcat. The reportEvent family does not pass through this handler; those interfaces are stubs.
This table describes the Android Java/Kotlin SDK. On C ABI platforms (Linux, Windows, OpenHarmony, iOS, and macOS), MigoHostCallbacks currently covers lifecycle, soft keyboard, and frame driving; commerce callbacks are not yet exposed through the C ABI. The fallback behavior documented here is therefore the complete behavior on those platforms.
Two contract tests protect critical behavior. test-ad-reward-integrity-contract.sh enforces “no ad, no reward.” test-permission-coverage-contract.sh derives the permission-gated interface set directly from source. Neither relies on a manually maintained list.
Integration examples are in migo-examples. Interface definitions are under platforms/android/library/src/main/java/com/migo/runtime/callback/ in the engine repository.