How Do I Get Started with the React Native SDK (v3)?

Install Gameball React Native SDK v4.0.0

Getting Started

Requirements

• React Native: 0.70+
• Node.js: 18+
• TypeScript: 4.0+ (optional but recommended)
• iOS: iOS 15.0+
• Android: API level 24+ (Android 7.0)

Upgrading from v3? Version 4.0.0 raises the minimum versions to iOS 15.0 and Android API 24. Every v3 call works unchanged. See Migration Notes.

Install the SDK

Install the package using npm or yarn:

npm

npm install react-native-gameball@^4.0.0

Install Peer Dependencies

The SDK requires five peer dependencies. Install them alongside it:

npm

npm install @react-native-async-storage/async-storage react-native-device-info react-native-modal react-native-push-notification-popup react-native-webview

react-native-safe-area-context is optional. When your app has it, in-app messages sit exactly clear of the notch and the home indicator.

iOS Setup

Navigate to the iOS folder and install pods:

cd ios && pod install && cd ..

Make sure your iOS deployment target is at least 15.0 in ios/Podfile:

platform :ios, '15.0'

Set IPHONEOS_DEPLOYMENT_TARGET to 15.0 for your app target in Xcode as well.

Android Setup

Ensure INTERNET permission is declared in android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />

Your android/app/build.gradle should have minimum SDK version 24:

android {
    defaultConfig {
        minSdkVersion 24
        targetSdkVersion 34
    }
}

ProGuard Configuration (Android)

If using ProGuard, add to android/app/proguard-rules.pro:

-keep class com.gameballsdk.** { *; }
-keepnames class * extends com.gameballsdk.**
-dontwarn com.gameballsdk.**

Metro Configuration

Add to your metro.config.js:

const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');

const config = {
  resolver: {
    assetExts: ['bin', 'txt', 'jpg', 'png', 'json', 'woff', 'woff2', 'ttf', 'otf'],
  },
};

module.exports = mergeConfig(getDefaultConfig(__dirname), config);

Verify Installation

Import the package in your code to verify:

import { GameballApp } from 'react-native-gameball';

If there are no import errors, you’re ready to initialize the SDK!

Troubleshooting

Common Issues

Widget Not Displaying

Symptoms: Profile widget doesn’t appear when called

Solutions:

• Ensure react-native-webview is properly installed and linked
• Check that the API key is valid and the customer is initialized
• Verify network connectivity
• Check console for error messages

Build Errors on iOS

Symptoms: Pod installation or build failures

Solutions:

• Clean build folder: cd ios && xcodebuild clean
• Reinstall pods: cd ios && pod install --repo-update
• Ensure iOS deployment target is at least 15.0
• Try pod deintegrate && pod install

Build Errors on Android

Symptoms: Gradle build failures

Solutions:

• Clean gradle cache: cd android && ./gradlew clean
• Verify minimum SDK version is 24
• Check React Native version compatibility
• Ensure all dependencies are properly installed

TypeScript Errors

Symptoms: Type definition errors

Solutions:

• Ensure TypeScript version is 4.0+
• Run npx tsc --noEmit to check type errors
• Verify type definitions are imported correctly
• Clear TypeScript cache if needed

Metro Bundler Issues

Symptoms: Asset loading errors or bundling failures

Solutions:

• Clear Metro cache: npx react-native start --reset-cache
• Ensure Metro configuration includes necessary asset extensions
• Check metro.config.js configuration

Debug Logging

For detailed debug logging during development:

# iOS
npx react-native run-ios --verbose

# Android
npx react-native run-android --verbose

Use the --verbose flag when running your app to see detailed SDK logs and network operations during development.

In-app messaging logs separately, prefixed [GameballIAM]. See In-App Messaging.

Next Steps

• Initialize SDK
• Initialize Customer Profile