Ad API

Reward actions such as rewarded video, banner, and share have been unified into a single slot model since v0.2.0. Use the lookup APIs (getRewardedAdSlots / getRewardedAdSlot) to fetch active slots and render them, then run a slot with a single showRewardedAd({ slotId }) call when the user taps it. To show only a rewarded video ad without a slot, you can still use showRewardedAd({ adUnitId }) as before.

`showRewardedAd(options)` (Recommended)

Runs a rewarded ad / reward action in a single call. If slotId is provided, it runs the slot's action (video/banner/share); otherwise it runs a rewarded video ad using adUnitId. The platform automatically handles loading, display, retry on failure, and user notifications.

Options:

Parameter	Type	Required	Description
`slotId`	`string`	△	Reward slot ID (obtained from `getRewardedAdSlots` / `getRewardedAdSlot`). Takes precedence.
`adUnitId`	`string`	△	Ad unit ID. Runs a rewarded video ad when `slotId` is not specified.
`success`	`function`	-	Success callback
`fail`	`function`	-	Failure callback
`complete`	`function`	-	Completion callback

Both slotId and adUnitId are optional, but at least one must be provided. If both are present, slotId takes precedence.

Success Response:

Field	Type	Description
`isEnded`	`boolean`	Whether the reward was completed (eligible for reward)
`errMsg`	`string`	Result message

// 1) Run a reward slot (recommended)
TudadaSDK.showRewardedAd({
  slotId: slot.slotId,
  success: (res) => {
    if (res.isEnded) {
      giveReward();   // The game grants the reward itself
    }
  },
  fail: (err) => console.error('Reward action failed:', err.errMsg),
});

// 2) Run a rewarded video ad directly
TudadaSDK.showRewardedAd({
  adUnitId: 'your-ad-unit-id',
  success: (res) => {
    if (res.isEnded) giveReward();
  },
});

Note: When loading fails, the platform automatically retries and displays a notification popup on final failure. There is no need to implement separate error handling UI in your game. When isEnded is true, the user is eligible for a reward, and the game grants the actual reward itself.

`showRewardedAdAsync(options)`

Promise version of showRewardedAd(). Options are the same, and the reward-completion status is returned as Promise<ShowRewardedAdResult>.

const result = await TudadaSDK.showRewardedAdAsync({ slotId: slot.slotId });
if (result.isEnded) {
  giveReward();
}

Unified Reward Slot

The reward slot is a v0.2.0 unified API that handles rewarded video, banner, and share as a single model. The game fetches the list of active slots, renders them directly from slotData, and runs showRewardedAd({ slotId }) when the user taps.

Each slot has the following structure.

Field	Type	Description
`slotId`	`string`	Slot identifier (specified at run time)
`action`	`string`	Action type (`'REWARD_VIDEO'` \| `'BANNER'` \| `'SHARE'`)
`slotData`	`object?`	Data for game-side rendering (optional)
`slotData.imageUrl`	`string?`	Slot image URL (game renders directly)
`slotData.title`	`string?`	Slot title
`slotData.expiresAt`	`number?`	Expiration time (Unix ms)

Default rewarded video and share slots may have no slotData, as they have no visual elements to render. Banner slots usually include slotData.imageUrl.

`getRewardedAdSlots(options?)`

Retrieves the full list of active reward slots.

Options:

Parameter	Type	Required	Description
`success`	`function`	-	Success callback
`fail`	`function`	-	Failure callback
`complete`	`function`	-	Completion callback

Success Response:

Field	Type	Description
`slots`	`RewardedAdSlot[]`	List of active slots
`errMsg`	`string`	Result message

TudadaSDK.getRewardedAdSlots({
  success: ({ slots }) => {
    slots.forEach((slot) => {
      if (slot.slotData?.imageUrl) renderSlot(slot);
    });
  },
});

`getRewardedAdSlotsAsync()`

Promise version of getRewardedAdSlots().

const { slots } = await TudadaSDK.getRewardedAdSlotsAsync();

`getRewardedAdSlot(options)`

Retrieves a single slot by slotId. If the slot does not exist, the fail callback is called.

Options:

Parameter	Type	Required	Description
`slotId`	`string`	✅	Slot ID to retrieve
`success`	`function`	-	Success callback
`fail`	`function`	-	Failure callback (including slot not found)
`complete`	`function`	-	Completion callback

Success Response:

Field	Type	Description
`slot`	`RewardedAdSlot`	Slot information
`errMsg`	`string`	Result message

TudadaSDK.getRewardedAdSlot({
  slotId: 'main_menu_reward',
  success: ({ slot }) => renderSlot(slot),
  fail: (err) => console.warn('Slot not found:', err.errMsg),
});

`getRewardedAdSlotAsync(slotId)`

Promise version of getRewardedAdSlot(). The slot ID is passed directly as an argument, and the promise rejects if the slot does not exist.

try {
  const { slot } = await TudadaSDK.getRewardedAdSlotAsync('main_menu_reward');
  renderSlot(slot);
} catch (e) {
  // No reward to display for the slot — skip UI
}

Full flow:

// 1) Look up active slots
const { slots } = await TudadaSDK.getRewardedAdSlotsAsync();

// 2) Render slots (the game does this directly)
slots.forEach((slot) => {
  if (!slot.slotData?.imageUrl) return;
  const el = renderSlotButton(slot.slotData);

  // 3) Run on user tap
  el.onclick = async () => {
    const res = await TudadaSDK.showRewardedAdAsync({ slotId: slot.slotId });
    if (res.isEnded) giveReward();   // The game grants the reward itself
  };
});

`createRewardedVideoAd(options)` (Legacy)

Deprecated

createRewardedVideoAd is a legacy API and will be removed in a future version. Use the unified showRewardedAd() or showRewardedAdAsync() instead.

Creates a rewarded video ad instance.

Options:

Parameter	Type	Required	Description
`adUnitId`	`string`	✅	Ad unit ID
`multiton`	`boolean`	-	Multi-instance mode

Note: Currently only a single ad is supported, and the ad ID is controlled by the platform, so any string can be passed to adUnitId.

Instance Methods:

Member	Type	Description
`load()`	`Promise<void>`	Load the ad
`show()`	`Promise<void>`	Show the ad
`destroy()`	`void`	Destroy the instance
`onLoad(callback)`	`void`	Load complete event
`onError(callback)`	`void`	Error event
`onClose(callback)`	`void`	Close event
`offLoad(callback?)`	`void`	Unregister load event
`offError(callback?)`	`void`	Unregister error event
`offClose(callback?)`	`void`	Unregister close event

// Create ad instance
const rewardedAd = TudadaSDK.createRewardedVideoAd({
  adUnitId: 'your-ad-unit-id',
});

// Register event listeners
rewardedAd.onLoad(() => {
  console.log('Ad loaded');
});

rewardedAd.onError((err) => {
  console.error('Ad error:', err.errMsg, err.errCode);
});

rewardedAd.onClose((res) => {
  if (res.isEnded) {
    // User watched the ad to completion → grant reward
    console.log('Reward granted!');
    giveReward();
  } else {
    // User closed the ad early
    console.log('Ad closed early');
  }
});

// Load and show ad
rewardedAd.load()
  .then(() => rewardedAd.show())
  .catch((err) => console.error('Ad display failed:', err));

Deprecated

The banner ad APIs (getAvailableBannerIds / getBanner / runBannerAction) have been replaced by the unified reward slot and are retained for compatibility. For new integrations, fetch slots with getRewardedAdSlots() and run them with showRewardedAd({ slotId }) (action=BANNER).

Banner ads use a slot model: the game defines slot positions on screen (e.g., "main_menu_top") and renders the ad image itself. The SDK handles only the image URL delivery and action processing; rendering, tap detection, and reward dispatch are the game's responsibility.

bannerId is a slot identifier doubling as the banner id.
When the user taps the banner, the game calls runBannerAction(bannerId) to delegate action processing to the SDK.
The response carries success / fail signals only. Reward dispatch happens inside the game.

`getAvailableBannerIds(options)`

Retrieves the list of currently active banner slot IDs. Since games typically know their slot names statically, this API is for operational metadata.

Options:

Parameter	Type	Required	Description
`success`	`function`	-	Success callback
`fail`	`function`	-	Failure callback
`complete`	`function`	-	Completion callback

Success Response:

Field	Type	Description
`bannerIds`	`string[]`	Array of active slot names
`errMsg`	`string`	Result message

TudadaSDK.getAvailableBannerIds({
  success: ({ bannerIds }) => {
    console.log('Active slots:', bannerIds);
  },
});

`getAvailableBannerIdsAsync()`

Promise version of getAvailableBannerIds().

const { bannerIds } = await TudadaSDK.getAvailableBannerIdsAsync();

`getBanner(options)`

Fetches the banner data matched to a given slot. If no ad is matched to the slot, the fail callback is called.

Options:

Parameter	Type	Required	Description
`bannerId`	`string`	✅	Banner ID (doubles as slot name)
`success`	`function`	-	Success callback
`fail`	`function`	-	Failure callback (includes "no match")
`complete`	`function`	-	Completion callback

Success Response:

Field	Type	Description
`banner.bannerId`	`string`	Banner ID (doubles as slot name)
`banner.imageUrl`	`string`	Banner image URL (game renders directly)
`banner.expiresAt`	`number?`	Optional expiration time (Unix ms)
`errMsg`	`string`	Result message

TudadaSDK.getBanner({
  bannerId: 'main_menu_top',
  success: ({ banner }) => {
    const img = document.createElement('img');
    img.src = banner.imageUrl;
    document.body.appendChild(img);
  },
  fail: (err) => {
    console.warn('No ad available for this slot:', err.errMsg);
  },
});

`getBannerAsync(bannerId)`

Promise version of getBanner(). Rejects when no ad is matched.

try {
  const { banner } = await TudadaSDK.getBannerAsync('main_menu_top');
  renderBanner(banner.imageUrl);
} catch (e) {
  // No ad matched to slot — skip rendering
}

`runBannerAction(options)`

Called by the game on user banner tap. The SDK processes the action (deeplink/external link/etc.) and notifies success / fail only.

Reward dispatch happens inside the game.

Options:

Parameter	Type	Required	Description
`bannerId`	`string`	✅	Banner ID (doubles as slot name)
`success`	`function`	-	Success callback — game grants reward, etc.
`fail`	`function`	-	Failure callback
`complete`	`function`	-	Completion callback

img.onclick = () => {
  TudadaSDK.runBannerAction({
    bannerId: 'main_menu_top',
    success: () => {
      grantReward();   // game-side reward dispatch
    },
    fail: (err) => {
      showToast(err.errMsg);
    },
  });
};

`runBannerActionAsync(bannerId)`

Promise version of runBannerAction().

img.onclick = async () => {
  try {
    await TudadaSDK.runBannerActionAsync('main_menu_top');
    grantReward();
  } catch (e) {
    showToast('Action failed');
  }
};

Ad API​

showRewardedAd(options) (Recommended)​

showRewardedAdAsync(options)​

Unified Reward Slot​

getRewardedAdSlots(options?)​

getRewardedAdSlotsAsync()​

getRewardedAdSlot(options)​

getRewardedAdSlotAsync(slotId)​

createRewardedVideoAd(options) (Legacy)​

Banner Ad (Slot Model)​

getAvailableBannerIds(options)​

getAvailableBannerIdsAsync()​

getBanner(options)​

getBannerAsync(bannerId)​

runBannerAction(options)​

runBannerActionAsync(bannerId)​

Ad API

`showRewardedAd(options)` (Recommended)

`showRewardedAdAsync(options)`

Unified Reward Slot

`getRewardedAdSlots(options?)`

`getRewardedAdSlotsAsync()`

`getRewardedAdSlot(options)`

`getRewardedAdSlotAsync(slotId)`

`createRewardedVideoAd(options)` (Legacy)

Banner Ad (Slot Model)

`getAvailableBannerIds(options)`

`getAvailableBannerIdsAsync()`

`getBanner(options)`

`getBannerAsync(bannerId)`

`runBannerAction(options)`

`runBannerActionAsync(bannerId)`