> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gameball.co/llms.txt
> Use this file to discover all available pages before exploring further.

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

> 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)

> [!NOTE]
>
> **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](https://docs.gameball.co/installation-guides/v4/react-native/migration-notes.md).

## Install the SDK

Install the package using npm or yarn:

```bash npm theme={null}
npm install react-native-gameball@^4.0.0
```

```bash yarn theme={null}
yarn add react-native-gameball@^4.0.0
```

## Install Peer Dependencies

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

```bash npm theme={null}
npm install @react-native-async-storage/async-storage react-native-device-info react-native-modal react-native-push-notification-popup react-native-webview
```

```bash yarn theme={null}
yarn add @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:

```bash theme={null}
cd ios && pod install && cd ..
```

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

```ruby theme={null}
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`:

```xml theme={null}
<uses-permission android:name="android.permission.INTERNET" />
```

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

```gradle theme={null}
android {
    defaultConfig {
        minSdkVersion 24
        targetSdkVersion 34
    }
}
```

## ProGuard Configuration (Android)

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

```proguard theme={null}
-keep class com.gameballsdk.** { *; }
-keepnames class * extends com.gameballsdk.**
-dontwarn com.gameballsdk.**
```

## Metro Configuration

Add to your `metro.config.js`:

```javascript theme={null}
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:

```typescript theme={null}
import { GameballApp } from 'react-native-gameball';
```

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

## Troubleshooting

### Common Issues

> [accordion] 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

> [accordion] 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`

> [accordion] 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

> [accordion] 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

> [accordion] 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:

```bash theme={null}
# iOS
npx react-native run-ios --verbose

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

> [!TIP]
>
> 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](https://docs.gameball.co/installation-guides/v4/react-native/in-app-messaging.md#logging-and-troubleshooting).

## Next Steps

* [Initialize SDK](https://docs.gameball.co/installation-guides/v4/react-native/initialize-sdk.md)
* [Initialize Customer Profile](https://docs.gameball.co/installation-guides/v4/react-native/initialize-profile.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.