Docs
SDKs

React Native SDK

Expo and bare React Native support with native views and TypeScript types.

Prompt for coding agents

I want to set up Koah's React Native SDK. Read https://docs.koahlabs.com/SKILL.md and follow its instructions.

Koah 1.0 is stable. 1.0.0 is live on npm — pin the exact version shown below. Upgrading from 0.x? Follow the migration guide. Questions: support@koahlabs.com.

Prerequisites

  • A Koah account — if you don't have one, apply for access
  • Your publisher ID from the dashboard
  • React >= 18.0.0 and React Native >= 0.70.0 (declared as peer dependencies), Node >= 22.0.0

Install

1

Install the package

Expo

npx expo install koah-react-native@1.0.0 expo-file-system expo-application expo-device react-native-webview

Bare React Native

yarn add koah-react-native@1.0.0 @react-native-async-storage/async-storage react-native-device-info react-native-webview

Using React Native Web or React Native macOS? Skip expo-file-system (unsupported on those platforms) and use @react-native-async-storage/async-storage instead.

2

Initialize the SDK

Call Koah.init once at module scope, then wrap your app with KoahProvider, passing the instance as client, and add the KoahBrowserModal component at the top level of your app hierarchy.

import { Koah, KoahProvider, KoahBrowserModal } from 'koah-react-native'

const koah = Koah.init({ publisherId: 'YOUR_PUBLISHER_ID' })

export default function App() {
  return (
    <KoahProvider client={koah}>
      <YourApp />

      {/* Required: browser modal for ad interactions */}
      <KoahBrowserModal />
    </KoahProvider>
  )
}
3

Display an ad

Add an ad component where you want it to render. The SDK provides two — KoahTextAdComponent for ads after AI responses, and KoahFeedAdComponent for ads in social feeds and content streams. Each takes an adContext describing the surface (see Ad context).

// Render after an AI response
<KoahTextAdComponent
  adContext={KoahAdContext.conversation({ question, answer })}
  cacheKey={messageId}
/>
4

Theme & size your adsOptional

Theme ads to match your brand and bound each slot's size from one place — see theming and sizing on the Appearance page.

Best Practices

  • Initialize early: Call Koah.init at app entry (module scope), outside the UI tree, and pass the instance to KoahProvider via client — configuration errors then surface at your own call site instead of mid-render
  • Use stable cache keys: Pass a unique, stable cacheKey per slot (and an externalConversationId on KoahAdContext.conversation(...) to group multi-turn conversations) for better tracking — see How it works for cache-key and prefetch behavior

Slots

Tag an ad request with a slot to break down your dashboard reporting by where the ad renders — a feed card, an in-article unit, a chat sidebar. Register your slots in the dashboard first.

slot is passed on the imperative requestAd / prefetchAd calls — the KoahTextAdComponent / KoahFeedAdComponent props don't expose it. Get the SDK instance from Koah.init, warm a placement tagged with its slot, then render it with KoahCachedAdComponent:

import { Koah, KoahAdContext } from 'koah-react-native'

const koah = Koah.init({ publisherId: 'YOUR_PUBLISHER_ID' })

await koah.prefetchAd({
  adContext: KoahAdContext.feed({ text: post.text, source: post.source }),
  cacheKey: post.id,
  slot: 'in-article',
})

Render the warmed ad with <KoahCachedAdComponent cacheKey={post.id} /> — it reads the cached fill by key. requestAd takes the same slot for the one-shot flow.

An unregistered slot resolves to no-fill (kind: "noFill") and nothing renders — register it in the dashboard before shipping. See Slots for setup, naming rules, and reporting.

Next Steps

Was this helpful?