Amazon Vega OS setup for the SofAds SDK

Vega OS is Amazon's operating system for newer Fire TV devices, next to the Android-based Fire OS. Vega apps are written in React Native for Vega, and a web app runs there inside Vega's WebView, a Chromium-based web view. So your HTML5 app keeps its code: you wrap it in a small host app with one full-screen WebView, and the same sofads.min.js you ship on Tizen, webOS, Whale TV and Titan OS runs inside it unchanged.

SofAds supports Vega OS for WebView apps. There is no Vega inventory for advertisers yet, so until there is, expect mostly test ads and house ads on Vega. Native React Native for Vega apps without a WebView are not supported; a native SDK may come later.

How it fits together

1. Your web app (HTML, JavaScript, the SofAds SDK) is packaged into the Vega app's assets, or loaded from your own website.
2. The host app is a React Native for Vega project with one WebView that fills the screen and has the focus.
3. The advertising ID bridge. A web page can't read Amazon's advertising ID. The host app reads it with Amazon's AdIdRetriever and hands it to the page as window.SofAdsHost, before your scripts run. The SDK reads it there, the same way it reads webapis on Tizen.

The host contract is one small object:

Field	Value
platform	"vega"
ifa	Amazon's advertising ID from AdIdRetriever.fetchAdvertisingId(), or empty
lmt	1 when AdIdRetriever.isAdvertisingTrackingEnabled() is false (the user turned off interest-based ads), else 0
nativeAppId	Your package ID from manifest.toml

Values the host only knows later can be pushed into the page at any time with injectJavaScript, as a sofads:host event; they are merged into window.SofAdsHost:

window.dispatchEvent(new CustomEvent("sofads:host", { detail: { ifa: "…", lmt: 1 } }));

Without the bridge, ads still work: the SDK uses its own resettable install ID.

The host app

Create a React Native for Vega project with the Vega SDK (Amazon's WebView template is a good start), then add the WebView and the ad ID packages:

npm install @amazon-devices/webview @amazon-devices/kepler-adid-retriever

src/App.tsx (the same host as in the SDK's own README):

import React, { useEffect, useMemo, useRef } from 'react';
import { AppState, StyleSheet, View } from 'react-native';
import { WebView } from '@amazon-devices/webview';
import { AdIdRetriever } from '@amazon-devices/kepler-adid-retriever';

const PACKAGE_ID = 'com.yourstudio.snowstrike'; // package.id in manifest.toml
const GAME_URL = 'https://games.yourstudio.com/snowstrike/'; // or your packaged web build

// Both calls are synchronous. The ID comes back whatever the tracking state; the
// tracking state decides whether it may be used for interest-based ads (lmt).
function hostValues() {
  let ifa = '';
  let tracking = false;
  try { ifa = AdIdRetriever.fetchAdvertisingId(); } catch (e) { /* no ad ID service: the SDK uses its install ID */ }
  try { tracking = AdIdRetriever.isAdvertisingTrackingEnabled(); } catch (e) { /* unknown: treat as off */ }
  return { platform: 'vega', ifa: ifa, lmt: tracking ? 0 : 1, nativeAppId: PACKAGE_ID };
}

export const App = () => {
  const webRef = useRef<any>(null);
  // Runs before the page's own scripts, so SofAds.init() already sees the values.
  const beforeLoad = useMemo(() => 'window.SofAdsHost = ' + JSON.stringify(hostValues()) + '; true;', []);

  useEffect(() => {
    // Back in the foreground: the user may have changed the ad setting meanwhile.
    const sub = AppState.addEventListener('change', (state) => {
      if (state !== 'active') return;
      webRef.current?.injectJavaScript(
        "window.dispatchEvent(new CustomEvent('sofads:host', { detail: " + JSON.stringify(hostValues()) + ' })); true;',
      );
    });
    return () => sub.remove();
  }, []);

  return (
    <View style={styles.container}>
      <WebView
        ref={webRef}
        source={{ uri: GAME_URL }}
        hasTVPreferredFocus={true}              // D-pad focus goes to the game
        javaScriptEnabled={true}
        domStorageEnabled={true}                // localStorage: the SofAds install ID and bootstrap cache
        allowSystemKeyEvents={true}             // BACK reaches the page (keyCode 27)
        mediaPlaybackRequiresUserAction={false} // video ads start without a click
        injectedJavaScriptBeforeContentLoaded={beforeLoad}
      />
    </View>
  );
};

const styles = StyleSheet.create({ container: { flex: 1 } });

What each setting does:

• domStorageEnabled turns on localStorage, which is off by default in Vega's WebView. The SDK keeps its install ID, frequency caps and cached config there, so without it every launch looks like a new user.
• source is your hosted game URL (see hosted apps), or the web build packaged in the host app's assets/ folder: file:///pkg/assets/index.html. The WebView loads from /pkg/assets by default; only other folders need the allowFileAccess prop.
• hasTVPreferredFocus gives the WebView the focus at launch, so the remote's keys reach your page.
• allowSystemKeyEvents lets the page receive BACK (see BACK and focus).
• mediaPlaybackRequiresUserAction={false} lets video ads start without a click; a TV remote has no click.
• injectedJavaScriptBeforeContentLoaded runs the host script after the document is created and before your scripts, so window.SofAdsHost is there when the SDK starts.
• The AppState listener sends fresh values as a sofads:host event when the app comes back to the foreground, because the user may have changed the interest-based ads setting meanwhile.

Your web page then starts the SDK as on every other platform. Every call, option and event is in the SDK reference.

<!-- assets/index.html in the host app -->
<script src="js/sofads.min.js"></script>
<script>
  // Platform, advertising ID and package ID come from window.SofAdsHost.
  SofAds.init({ appId: "sof_YOUR_APP_ID" });
</script>

Your Vega app ID

When you add an Amazon Vega OS listing, the dashboard asks for your package ID. It is the id under [package] in the host app's manifest.toml, in reverse-domain style, for example com.yourstudio.snowstrike. Amazon allows letters, digits, periods and underscores in reverse-DNS notation, with at least two parts that each start with a letter. The ID has to be unique in the Amazon Appstore and must never change, or updates break. If you also have a Fire OS (Android) version and want one store listing for both, Amazon requires the same package name in both builds.

A web page can't read manifest.toml, so the host app passes the same value as nativeAppId in window.SofAdsHost (above). A listing with an ID only accepts traffic that reports that ID, so keep it the same in every release.

manifest.toml

The lines that matter for SofAds and for a WebView app. Merge them into the manifest.toml your project template created; keep its [os.version], [needs] and runtime module entries as the Vega SDK generated them.

schema-version = 1

[package]
title = "Snowstrike"
version = "1.0.0"
id = "com.yourstudio.snowstrike"   # your package ID = the dashboard's app ID

[components]
[[components.interactive]]
id = "com.yourstudio.snowstrike.main"
launch-type = "singleton"
categories = ["com.amazon.category.main"]   # needed to launch from the Fire TV home screen

[wants]
# Video ads and video in your app
[[wants.service]]
id = "com.amazon.media.server"
[[wants.service]]
id = "com.amazon.mediametrics.service"
[[wants.service]]
id = "com.amazon.mediabuffer.service"
[[wants.service]]
id = "com.amazon.mediatransform.service"

# Sound, audio focus and volume
[[wants.service]]
id = "com.amazon.audio.stream"
[[wants.service]]
id = "com.amazon.audio.control"

# Group-IPC, which the WebView needs to reach the media services
[[wants.service]]
id = "com.amazon.gipc.uuid.*"

# Amazon's advertising ID (AdIdRetriever)
[[wants.service]]
id = "com.amazon.admanager.service.main"

[offers]
[[offers.service]]
id = "com.amazon.gipc.uuid.*"

The media, audio and Group-IPC entries are the ones in Amazon's WebView setup for Vega SDK 0.24. Add com.amazon.inputmethod.service under [wants] if your app uses text input with the on-screen keyboard.

The ad manager service is listed under [wants], not [needs]: when it is missing, the app still launches and the SDK falls back to its install ID. Without com.amazon.category.main, Amazon says the app can't start from the home screen and fails Appstore submission.

BACK and focus

• Arrow keys and OK reach your page as keydown events (ArrowUp, ArrowDown, ArrowLeft, ArrowRight, Enter) without extra settings.

• BACK reaches your page as keyCode 27 only with allowSystemKeyEvents. The WebView then consumes BACK, also when your page ignores it, so the host app no longer closes on BACK by itself. When BACK on your home screen should leave the app, send a message to the host, and let the host exit with BackHandler.exitApp(). In the page:

  document.addEventListener("keydown", (e) => {
    if (e.keyCode === 27 && onHomeScreen()) {
      window.ReactNativeWebView.postMessage("exit");
    }
  });

  And in the host, add BackHandler to the react-native import and this prop to the WebView:

  onMessage={(event) => {
    if (event.nativeEvent.data === "exit") BackHandler.exitApp();
  }}

• During an ad, the SofAds overlay handles OK and BACK itself, as on the other platforms, and gives the keys back when the ad closes.

• Spatial navigation. Vega's WebView moves the focus between focusable elements on the arrow keys by default. A game that handles the arrow keys itself calls preventDefault() in its keydown handler.

• One WebView. Only the last created WebView receives BACK, so keep your app in one.

Hosted apps

The host above loads your app from your website (GAME_URL). Then the same rules apply as for hosted apps on other platforms: one permanent domain, because localStorage and the SofAds install ID belong to it, and a pinned SDK version such as https://sdk.sofadsrv.com/sdk/v1.0.0/sofads.min.js, never a "latest" URL. The host script works the same way, because it runs before the hosted page's scripts too.

Amazon Appstore listing and app-ads.txt

Vega apps are submitted in the Amazon Developer Console, the same way as Fire OS apps: you upload the .vpkg file the Vega SDK builds, and select the Vega devices on the Fire TV tab of the device targeting screen.

1. Before submission, add the listing in the SofAds dashboard: platform Amazon Vega OS (Fire TV) and your package ID. Your app gets test ads until the listing is live.
2. The store URL. Once the app is live, its Appstore page has an Amazon product ID (ASIN), and the page is https://www.amazon.com/dp/ followed by that ID. Add that URL to the listing.
3. app-ads.txt. Put the SofAds line in app-ads.txt at the root of the developer website you enter in the Developer Console. SofAds and buyers find the file through that website, as on every platform (where it goes).
4. Ad policy. Amazon has its own advertising policies for Appstore apps; read them before you submit. Once a Fire TV app with ads is used 50,000 hours or more a month in the United States (30,000 in other countries), Amazon may contact you to integrate Amazon Publisher Services and give Amazon 30% of the app's ad impressions in that country, or 30% of its ad revenue where Amazon Publisher Services isn't available.

Privacy policy lines for Vega OS

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 Amazon Fire TV devices with Vega OS, the advertising identifier is Amazon's advertising ID, sent together with your interest-based ads setting. You can turn off interest-based ads in the Fire TV's privacy settings; with interest-based ads off, only non-personalized ads are shown.

Next steps

Test on a real Fire TV with Vega OS: a test ad at each placement, BACK during an ad, and BACK on your home screen. Then go through the release checklist. Store rules and IDs on all TV platforms are compared in Smart TV app monetization.

Frequently asked questions

Is there a separate SofAds SDK for Vega OS?

No. Vega runs web apps in a Chromium-based WebView, so the one sofads.min.js runs there as it is. Only the host app is Vega-specific, and it only passes the advertising ID.

What happens when the user turns off interest-based ads?

The host passes lmt: 1. The SDK still sends the advertising ID with that flag, as on the other platforms, so only non-personalized (contextual) demand may use it. With advertising consent missing, or in an app made for children, no advertising ID is sent at all (privacy).

Do I need the advertising ID bridge?

Ads work without it, on the SDK's install ID. Still add it before you submit: Amazon's advertising ID policy says apps that show interest-based ads must use Amazon's advertising ID and honor its opt-out, not another identifier. The bridge also lets partners recognize the device across apps, which usually pays better.

Sources

Checked on October 10, 2026, against the Vega SDK 0.24 docs. Platform rules change; when a source and this page disagree, the source wins.

1. Amazon Vega: Overview of WebView (setup, manifest services)
2. Amazon Vega: Develop your app with WebView (remote keys, allowSystemKeyEvents, messaging)
3. Amazon Vega API: WebView component reference
4. Amazon Vega API: Ad ID Retriever (package, manifest service, usage)
5. Amazon Vega API: AdIdRetriever class
6. Amazon Vega: App manifest, with its package and components sections
7. React Native for Vega: BackHandler
8. Amazon Vega: App submission
9. Amazon: Advertising ID policy
10. Amazon: Appstore advertising policies
11. IAB Tech Lab: app-ads.txt

Keep reading

• Test ads and test devices: what your app shows before its listing is live.
• Privacy and consent: which IDs the SDK reads per platform, and when.
• Release checklist: what to check before you submit.