Whale TV setup for the SofAds SDK

Whale TV apps are hosted web apps, so there is no package manifest to edit. Load the SDK from your own server and, once Whale gives you access to the advertising ID, hand it to the SDK.

Load the SDK

Whale says apps don't need vendor-specific JavaScript libraries. Serve sofads.min.js from your own domain next to your app, or reference a pinned version on sdk.sofadsrv.com (never an unversioned "latest" URL).

<!-- index.html on your server -->
<script src="/js/sofads.min.js"></script>
<script>
  SofAds.init({
    appId: "sof_YOUR_APP_ID",
    // Whale's WAID API is not public yet. Once Whale gives you a way to
    // read it, return it here; until then the SDK uses its install ID.
    whale: { getAdId: () => null },
  });
</script>

The full API is in the SofAds SDK reference.

Your Whale TV app ID

When you add a Whale TV listing, the dashboard asks for a Whale TV app ID. It is optional. Whale apps are hosted web apps without a manifest, and Whale's developer docs define no app ID that an app can read on the TV, so the SDK can't detect one. You choose the value and pass it yourself:

• If Whale has given your app a store number, use it. Whale's ad macros call it the bundle ID, and it is the last part of the store URL, for example 20008274 in https://www.whaletv.com/apps/20008274.
• Otherwise use any stable name that is unique to your app, for example com.yourstudio.snowstrike.

Enter it in the dashboard and pass exactly the same value to the SDK:

SofAds.init({
  appId: "sof_YOUR_APP_ID",
  nativeAppId: "com.yourstudio.snowstrike", // the ID you entered in the dashboard
});

A listing with an ID only accepts traffic that reports that ID, so keep it the same in every release.

The WAID getter

Whale passes its advertising ID, the WAID, to ad servers through the [whale_ad_id] macro, but how a third-party app reads it on the TV is not publicly documented. The SDK therefore takes a getter, whale: { getAdId }, which may return the ID, null or a promise. Until it returns an ID, the SDK uses its own resettable install ID and sends it as ppid.

Whale also says you need cookies to identify a device. The SDK stores its install ID in localStorage, with a cookie as fallback, so keep both enabled for your app.

Privacy policy lines for Whale TV

Your app's privacy policy has to say that it shows ads and what data that involves. Copy these lines into it and adapt them to your app. They match the SofAds privacy policy, which is itself still a draft, so treat the wording as a template and have it reviewed for your app; it is not legal advice.

This app shows ads from SofAds. To choose, show and measure ads, the app sends SofAds information about the app and the TV (platform, manufacturer, model, operating system version, screen size and language), your IP address, your consent choices and an advertising identifier where your choices allow it. Where no TV advertising identifier is available or allowed, SofAds uses a random install ID stored by this app, which you can reset in the app's privacy settings. SofAds privacy policy: https://sofads.com/privacy/

On Whale TV, the advertising identifier is the Whale advertising ID (WAID), when the app can read it. You can reset or limit it in the TV's settings.

Next steps

Before the listing is live your app gets test ads. Whale's ad program and revenue models are covered in Whale TV monetization.

Frequently asked questions

Does Whale TV need a special library for SofAds?

No. Whale apps are hosted web apps without vendor libraries. You only load sofads.min.js and call SofAds.init.

What happens without the WAID?

Ads still work. The SDK uses its own random install ID, which the user can reset, and sends it as ppid.

Sources

Checked on October 7, 2026. Platform rules change; when a source and this page disagree, the source wins.

1. Whale TV Partner Portal: Development
2. Whale TV Partner Portal: Advertising
3. Whale TV Partner Portal: Ad macros

Keep reading

• Titan OS setup: the Titan SDK include and device info.
• Test ads and test devices: what your app shows before its listing is live.
• Whale TV monetization: Whale's ad program, WAID macros and open questions.