React Native Kickstart Exchange

A community-maintained React Native wrapper for Kickstart Exchange's SwiftUI banner on iOS 18+. This is not an official Kickstart product.

Requirements

• iOS 18.0 or later
• React Native 0.76 or later
• Expo Modules API
• A Kickstart Exchange API key for production builds

Android and other non-native platforms return null without rendering a banner.

Installation

Expo projects

npm install @tomyail/react-native-kickstart-exchange
npx expo install expo-build-properties

Set the iOS deployment target to 18.0 in app.json or app.config.js:

{
  "expo": {
    "plugins": [
      [
        "expo-build-properties",
        {
          "ios": {
            "deploymentTarget": "18.0"
          }
        }
      ]
    ]
  }
}

Then regenerate and build the native project:

npx expo prebuild
npx expo run:ios

Bare React Native projects

If Expo Modules are not installed yet:

npx install-expo-modules@latest

Install the package and CocoaPods dependency:

npm install @tomyail/react-native-kickstart-exchange
cd ios && pod install

Set the deployment target of the iOS app and Pods to 18.0 or later before building.

The package includes the required upstream SDK source, so you do not need to add a Swift Package manually in Xcode.

Usage

import { KickstartExchangeBanner } from "@tomyail/react-native-kickstart-exchange";

export function AdPlacement() {
  const apiKey =
    process.env.EXPO_PUBLIC_KICKSTART_EXCHANGE_KEY ??
    (__DEV__ ? "preview" : "");

  if (!apiKey) return null;

  return (
    <KickstartExchangeBanner
      apiKey={apiKey}
      style={{ marginHorizontal: 16, marginTop: 24 }}
      testID="kickstart-exchange-banner"
    />
  );
}

apiKey is required and must be non-empty. The default banner height is 164 points; pass a style to control its layout.

Theming and styling

The banner accepts optional style props that restyle the card without touching ad loading, reporting, or accessibility:

const { isDark, colors } = useAppTheme();

<KickstartExchangeBanner
  apiKey={apiKey}
  colorScheme={isDark ? "dark" : "light"}
  backgroundColor={colors.surface}
  cornerStyle="rounded"
  strokeColor={colors.border}
  disclosureBackgroundColor={colors.tint}
  actionTextColor={colors.tint}
/>;

• colorScheme — force the banner's light/dark appearance when your app's theme preference diverges from the system (dynamic colors, including the default .windowBackground card, follow it).
• backgroundColor — paint the card with your exact theme token.
• cornerStyle, strokeColor, disclosureBackgroundColor, actionTextColor — the upstream SDK's supported style seams.

Colors are hex strings (#RGB, #RGBA, #RRGGBB, #RRGGBBAA); invalid values are ignored in favor of SDK defaults and never crash. Props apply on updates — theme changes at runtime restyle the banner without reloading the ad. See Styling for defaults, limitations, and how the background seam works.

Preview mode

The upstream SDK accepts the literal preview key only in Debug builds and on the iOS Simulator. It loads a deterministic test advert without a Kickstart Exchange account.

Never use preview in a shipping build. Pass your live key through your app's build configuration instead.

Privacy and App Store disclosure

The bundled SDK privacy manifest declares Product Interaction and Advertising Data for Third Party Advertising, Developer Advertising, Analytics, and App Functionality.

Before shipping with a live key, review the SDK's current data practices and update your app's:

• App Store Connect App Privacy answers
• Privacy Policy
• Consent and regional disclosure flow, where applicable

See Privacy guidance and third-party notices.

Example app

A minimal Expo app is available in example/. Run it on an iOS 18+ Simulator with the preview key:

cd example
npm install
npx expo prebuild --clean --platform ios
npx expo run:ios

Troubleshooting

no such module 'KickstartExchange'

Run pod install again, confirm that the app deployment target is iOS 18.0 or later, and build the .xcworkspace rather than the .xcodeproj.

The banner is not visible

The SDK may be loading or may have no available advert. Confirm that the view has layout height, that the API key is valid, and that the app is active. The default wrapper height is 164 points.

Android renders nothing

This package currently supports iOS only. Android intentionally returns null.

Versioning

Releases use Conventional Commits and git-cliff. New versions are published to npm from matching Git tags such as v0.1.0.

For contributing, upstream SDK synchronization, and release maintenance, see the documents in docs/.

License

This wrapper is MIT licensed. The bundled KickstartSDK source is separately MIT licensed by Paul Hudson. See third-party notices.