Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(playable): pass store destinations through the CTA bridge

yhh0948e006dadc
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6ff508319..61bf87bcd 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,8 @@ published separately; it ships inside the editor.
### Fixed
+- **MRAID store clicks carry their destination.** `playableCta(url)` forwards an explicit store link, with host-provided `clickTag` as the MRAID fallback. Missing and malformed destinations no longer call `mraid.open` with no URL. HTTP(S), Android market and iOS App Store schemes are supported; other networks retain their host-selected store destinations.
+
- **UI text fades reuse cached geometry.** Inherited opacity changes update vertex alpha without repeating glyph lookup, layout or index generation. Bitmap and SDF text retain their original fill, rich-text, shadow and outline alpha, restoring it without cumulative fading; authored color and layout changes still rebuild the cache.
diff --git a/docs/astro/src/content/docs/publishing/overview.mdx b/docs/astro/src/content/docs/publishing/overview.mdx
index 7b6c08818..b7d28259e 100644
--- a/docs/astro/src/content/docs/publishing/overview.mdx
+++ b/docs/astro/src/content/docs/publishing/overview.mdx
@@ -122,6 +122,8 @@ number to trust.
For Mintegral, call `playableGameEnd()` on a win or loss and `playableRetry()` when the player restarts. The runtime calls `gameReady()` after startup finishes and responds to `gameStart()` / `gameClose()`. Keep installation tied to a user gesture through `playableCta()`. See the `playable-ad` example and [official container checker](https://www.playturbo.com/review). Passing that checker does not replace campaign approval or device acceptance.
+MRAID store buttons must pass a destination with `playableCta(storeUrl)` or use a host-provided `window.clickTag`. HTTP(S), Android `market:` and iOS `itms-apps:` links are supported. Missing or invalid destinations produce a configuration warning without calling `mraid.open`. Other networks continue using their own store hooks.
+
### A network we don't ship
Define it yourself — the built-in networks are written against this exact contract,
diff --git a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
index ee783e64b..7990531de 100644
--- a/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
+++ b/docs/astro/src/content/docs/zh-cn/publishing/overview.mdx
@@ -106,6 +106,8 @@ playableCta();
Mintegral 中,胜负结束时调用 `playableGameEnd()`,玩家重玩时调用 `playableRetry()`。运行时在启动完成后调用 `gameReady()`,并响应 `gameStart()` / `gameClose()`;安装按钮通过用户手势调用 `playableCta()`。参见 `playable-ad` 示例和[官方容器检测工具](https://www.playturbo.com/review)。检测通过仍需广告审核和真机验收。
+MRAID 安装按钮须通过 `playableCta(storeUrl)` 传入目标地址,或由宿主提供 `window.clickTag`。支持 HTTP(S)、Android `market:` 和 iOS `itms-apps:` 商店链接;地址缺失或无效时提示配置问题,不调用 `mraid.open`。其他网络继续使用自己的商店接口。
+
### 我们没内置的平台
自己定义就行——内置的那几家写的就是这份契约,没有做不到的事。**打包项目 → 新建平台** 可以
diff --git a/examples/playable-ad/README.md b/examples/playable-ad/README.md
index 679d60fb0..9c6a849db 100644
--- a/examples/playable-ad/README.md
+++ b/examples/playable-ad/README.md
@@ -34,3 +34,9 @@ The `mraid`, `unity`, and `applovin` profiles wait for host readiness and viewab
A hidden ad pauses gameplay and audio; cleanup removes container listeners. Plain
browser preview remains active. Network upload and device acceptance remain separate
from a local mock-container check.
+
+For MRAID store buttons, pass your app’s destination to `playableCta(storeUrl)`
+or let the ad host supply `window.clickTag`. HTTP(S), Android `market:` and iOS
+`itms-apps:` store links are supported. Without a valid destination the bridge
+reports the missing configuration and does not call `mraid.open`. The sample
+project has no published app destination; configure yours before network acceptance.
diff --git a/pipeline/src/export/playableAdProfile.ts b/pipeline/src/export/playableAdProfile.ts
index 3b02cb55c..fadfe37b1 100644
--- a/pipeline/src/export/playableAdProfile.ts
+++ b/pipeline/src/export/playableAdProfile.ts
@@ -140,7 +140,12 @@ if(!subscribed)return;subscribed=false;
if(typeof host.removeEventListener==="function"){host.removeEventListener("ready",ready);host.removeEventListener("viewableChange",viewable);}
}
window.__ESTELLA_PLAYABLE__={
-cta:function(){if(window.mraid&&typeof window.mraid.open==="function")window.mraid.open();},
+cta:function(url){
+var target=url===undefined?window.clickTag:url,valid=false;
+try{var parsed=new URL(target);valid=typeof target==="string"&&!/\\s/.test(target)&&["http:","https:","market:","itms-apps:"].indexOf(parsed.protocol)>=0&&!!parsed.hostname;}catch(error){}
+if(!valid){console.warn("[playable] MRAID CTA needs a store URL passed to playableCta(url) or supplied as clickTag.");return;}
+if(window.mraid&&typeof window.mraid.open==="function")window.mraid.open(target);
+},
onActive:function(fn){subscribe();listeners.push(fn);fn(active);return function(){listeners=listeners.filter(function(item){return item!==fn;});if(!listeners.length)unsubscribe();};}
};
})();`;
diff --git a/pipeline/tests/platform-catalog.test.ts b/pipeline/tests/platform-catalog.test.ts
index 211d86db2..139c3079d 100644
--- a/pipeline/tests/platform-catalog.test.ts
+++ b/pipeline/tests/platform-catalog.test.ts
@@ -401,7 +401,7 @@ describe('playable ad networks', () => {
// the host webview injects mraid itself.
for (const id of ['mraid', 'unity', 'applovin']) {
const p = (await loadPlayableProfile(root, id))!;
- expect(p.emitBridge!({ title: 'T', orientation: 'landscape' })).toContain('mraid.open()');
+ expect(p.emitBridge!({ title: 'T', orientation: 'landscape' })).toContain('mraid.open(');
expect(p.emitHead).toBeUndefined();
}
// No selection ⇒ generic, so a project that never chose still exports.
diff --git a/pipeline/tests/playable-mraid.test.ts b/pipeline/tests/playable-mraid.test.ts
index 5fcb7b6b7..caad3bd9f 100644
--- a/pipeline/tests/playable-mraid.test.ts
+++ b/pipeline/tests/playable-mraid.test.ts
@@ -23,7 +23,7 @@ describe('MRAID lifecycle', () => {
c.ready(false); expect(active).toHaveBeenLastCalledWith(false);
c.viewable(true); expect(active).toHaveBeenLastCalledWith(true);
c.viewable(false); expect(active).toHaveBeenLastCalledWith(false);
- c.bridge.cta(); expect(c.mraid.open).toHaveBeenCalledOnce();
+ c.bridge.cta('https://example.com/store'); expect(c.mraid.open).toHaveBeenCalledWith('https://example.com/store');
release(); expect(c.events.get('ready')?.size).toBe(0); expect(c.events.get('viewableChange')?.size).toBe(0);
const previous = active.mock.calls.length; c.viewable(true); expect(active).toHaveBeenCalledTimes(previous);
});
@@ -38,10 +38,24 @@ describe('MRAID lifecycle', () => {
expect(again).toHaveBeenLastCalledWith(true); third();
});
+ it('uses a host clickTag and refuses missing or unsafe destinations', () => {
+ const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+ const window: any = { clickTag: 'https://example.com/store', mraid: { open: vi.fn() } };
+ new Function('window', mraidPlayableProfile.emitBridge!({ title: 'T', orientation: 'portrait' }))(window);
+ window.__ESTELLA_PLAYABLE__.cta(); expect(window.mraid.open).toHaveBeenCalledWith(window.clickTag);
+ window.mraid.open.mockClear(); delete window.clickTag;
+ for (const url of [undefined, '', 'javascript:alert(1)', 'https://example.com/with space', 'https://']) window.__ESTELLA_PLAYABLE__.cta(url);
+ expect(window.mraid.open).not.toHaveBeenCalled();
+ for (const url of ['market://details?id=com.example.game', 'itms-apps://itunes.apple.com/app/id123']) {
+ window.__ESTELLA_PLAYABLE__.cta(url); expect(window.mraid.open).toHaveBeenLastCalledWith(url);
+ }
+ warn.mockRestore();
+ });
+
it('keeps a standalone browser preview active with no MRAID container', () => {
const window: any = {};
new Function('window', mraidPlayableProfile.emitBridge!({ title: 'T', orientation: 'portrait' }))(window);
const active = vi.fn(); window.__ESTELLA_PLAYABLE__.onActive(active);
- expect(active).toHaveBeenCalledWith(true); expect(() => window.__ESTELLA_PLAYABLE__.cta()).not.toThrow();
+ expect(active).toHaveBeenCalledWith(true); expect(() => window.__ESTELLA_PLAYABLE__.cta('https://example.com/store')).not.toThrow();
});
});
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index d3bda2e21..6ab09968d 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -6211,7 +6211,7 @@ wasmBaseUrl: string | undefined
## PlayableAdBridge — interface @experimental
```
-cta: (() => void) | undefined
+cta: ((url?: string) => void) | undefined
gameEnd: (() => void) | undefined
onActive: ((listener: (active: boolean) => void) => () => void) | undefined
ready: (() => void) | undefined
@@ -12284,7 +12284,7 @@ ParticlePlugin
## playableCta — function @experimental
```
-(): void
+(url?: string): void
```
## playableGameEnd — function @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index d59f3b72f..b78d6933b 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -6414,7 +6414,7 @@ wasmBaseUrl: string | undefined
## PlayableAdBridge — interface @experimental
```
-cta: (() => void) | undefined
+cta: ((url?: string) => void) | undefined
gameEnd: (() => void) | undefined
onActive: ((listener: (active: boolean) => void) => () => void) | undefined
ready: (() => void) | undefined
@@ -12547,7 +12547,7 @@ ParticlePlugin
## playableCta — function @experimental
```
-(): void
+(url?: string): void
```
## playableGameEnd — function @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 3030b6a04..0115504b6 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -6206,7 +6206,7 @@ wasmBaseUrl: string | undefined
## PlayableAdBridge — interface @experimental
```
-cta: (() => void) | undefined
+cta: ((url?: string) => void) | undefined
gameEnd: (() => void) | undefined
onActive: ((listener: (active: boolean) => void) => () => void) | undefined
ready: (() => void) | undefined
@@ -12289,7 +12289,7 @@ ParticlePlugin
## playableCta — function @experimental
```
-(): void
+(url?: string): void
```
## playableGameEnd — function @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index ce33f6bdb..1f39a1a89 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -6499,7 +6499,7 @@ wasmBaseUrl: string | undefined
## PlayableAdBridge — interface @experimental
```
-cta: (() => void) | undefined
+cta: ((url?: string) => void) | undefined
gameEnd: (() => void) | undefined
onActive: ((listener: (active: boolean) => void) => () => void) | undefined
ready: (() => void) | undefined
@@ -12593,7 +12593,7 @@ ParticlePlugin
## playableCta — function @experimental
```
-(): void
+(url?: string): void
```
## playableGameEnd — function @experimental
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 94b32edc3..417538571 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -6213,7 +6213,7 @@ wasmBaseUrl: string | undefined
## PlayableAdBridge — interface @experimental
```
-cta: (() => void) | undefined
+cta: ((url?: string) => void) | undefined
gameEnd: (() => void) | undefined
onActive: ((listener: (active: boolean) => void) => () => void) | undefined
ready: (() => void) | undefined
@@ -12320,7 +12320,7 @@ ParticlePlugin
## playableCta — function @experimental
```
-(): void
+(url?: string): void
```
## playableGameEnd — function @experimental
diff --git a/sdk/src/runtime/playableCta.ts b/sdk/src/runtime/playableCta.ts
index 09c2adeac..04de93c4a 100644
--- a/sdk/src/runtime/playableCta.ts
+++ b/sdk/src/runtime/playableCta.ts
@@ -19,7 +19,7 @@
/** What the exported page installs on `globalThis` — one method per interaction. */
export interface PlayableAdBridge {
/** Hand the player off to the store, the way THIS network spells it. */
- cta?(): void;
+ cta?(url?: string): void;
ready?(): void;
gameEnd?(): void;
retry?(): void;
@@ -35,17 +35,14 @@ export function playableAdBridge(): PlayableAdBridge | undefined {
}
/**
- * Send the player to the store. Call it from whatever the ad's call-to-action is
- * (an end-card button, a tap after the win) — once, from game code, with no
- * network in sight.
- *
- * Silently does nothing outside a playable build, so the same scene runs in the
- * editor and on the web.
+ * Dispatch a user-gesture store click through the selected network.
+ * MRAID accepts an explicit store URL; other hosts select their own destination.
+ * Without a bridge, the scene remains playable and reports missing configuration.
*/
-export function playableCta(): void {
+export function playableCta(url?: string): void {
const cta = playableAdBridge()?.cta;
if (cta) {
- cta();
+ cta(url);
return;
}
if (!warned) {
diff --git a/sdk/tests/playable-cta.test.ts b/sdk/tests/playable-cta.test.ts
index 9393792bc..c66f05f22 100644
--- a/sdk/tests/playable-cta.test.ts
+++ b/sdk/tests/playable-cta.test.ts
@@ -23,6 +23,12 @@ describe('playableCta', () => {
expect(cta).toHaveBeenCalledTimes(1);
});
+ it('forwards an explicit store URL to the network bridge', () => {
+ const cta = vi.fn(); g[KEY] = { cta };
+ playableCta('https://example.com/store');
+ expect(cta).toHaveBeenCalledWith('https://example.com/store');
+ });
+
it('is a no-op with no bridge, so the same scene runs on the web', () => {
const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
expect(hasPlayableCta()).toBe(false);
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 77fccabce..9577ca76c 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(playable): pass store destinations through the CTA bridge':
+ { note: 'MRAID store clicks carry their destination.' },
'fix(playable): observe MRAID readiness and viewability':
{ note: 'MRAID playables wait for ready and viewable hosts.' },
'feat(playable): package TikTok and overseas Pangle creatives':