Guides
Start typing to search…

Installing the Expo SDK

Last Updated: Monday, March 30, 2026

This guide provides step-by-step instructions for installing and configuring the Vibes SDK in your Android & iOS React Native/Expo application using managed workflow with custom development build and Expo 51.

Applicable for Android only: The Vibes SDK for Android is distributed as an AAR (Android Archive) file, which is a binary library format that contains compiled Android code, resources, and manifest entries. AAR files are automatically included in your app during the build process through the Expo plugin system.

Why AAR files don't require credentials:

  • AAR files are pre-compiled libraries that contain the Vibes SDK's native Android code
  • They are stateless - they don't store any credentials or sensitive information
  • Authentication and configuration are handled at runtime through your app's configuration (via androidAppId and appUrl parameters)
  • The AAR file only provides the native interface - actual API calls and authentication happen when your app runs and connects to Vibes servers using your configured credentials

Prerequisites

Before you begin, ensure you have the following:

  • Expo CLI installed globally: npm install -g @expo/cli
  • EAS CLI installed: npm install -g eas-cli
  • React Native npm install [email protected]
  • Firebase npm install @react-native-firebase/app @react-native-firebase/messaging
  • Expo account (free or paid tier at expo.dev)
  • Node.js and npm or yarn
  • Java Development Kit (JDK) 11 or higher
  • Android SDK with API level 21+ (Android 5.0+)

Android

  • Android API Level: 21+ (Android 5.0 Lollipop)
  • Target SDK: 34 (Android 14)
  • Compile SDK: 34
  • Gradle Version: 7.0+

iOS

  • iOS Version: 13.0+
  • Xcode Version: 15.0+
  • Swift Version: 5.0+
  • Push Notifications: Must be configured in Apple Developer Portal
  • Entitlements: aps-environment must be set to development or production

Installation Steps

1. Install the Package

Add the Vibes SDK package to your project dependencies:

npm install vibes-react-native-expo
# or
yarn add vibes-react-native-expo

If you continue to encounter errors while installing the Vibes SDK, you can install it using the --legacy-peer-deps flag to ensure the Expo dependencies compatibility and the SDK is installed correctly

npm install vibes-react-native-expo --legacy-peer-deps

2. Configure the Plugin

Add the Vibes plugin configuration to your app.config.ts file:

import { ExpoConfig } from "expo/config";


export default {
 expo: {
   // ... other expo config
   plugins: [
     [
       "vibes-react-native-expo",
       {
         androidAppId: process.env.ANDROID_APP_ID, 
         appUrl: process.env.APP_URL,
         iosAppId: process.env.IOS_APP_ID,
         vibesAppEnv: process.env.VIBES_APP_ENV || "UAT",
         apsEnvironment: process.env.APP_ENV || "development", // or "production"
       },
     ],
   ],
   ios: {
     bundleIdentifier: "com.yourcompany.yourapp",
     entitlements: {
       "aps-environment": "development"
     }
   },
   android: {
     package: "com.yourcompany.yourapp",
     // ... other android config
   },
 },
};

3. Environment Variables

In app.config.ts, you can reference environment variables directly using process.env.ANDROID_APP_ID, process.env.APP_URL, process.env.IOS_APP_ID, and process.env.VIBES_APP_ENV (no EXPO_PUBLIC_ prefix needed), because the config is loaded at build time, not at runtime. Create a .env file in your project root and add your Vibes credentials:

ANDROID_APP_ID=your-android-app-id-here
IOS_APP_ID=your-ios-app-id-here
APP_URL=https://your-vibes-api-url.com/mobile_apps
VIBES_APP_ENV=UAT
APP_ENV=development

Then update your app.config.ts:

export default {
 expo: {
   plugins: [
     [
       "vibes-react-native-expo",
       {
         androidAppId: process.env.ANDROID_APP_ID,
         appUrl: process.env.APP_URL,
         iosAppId: process.env.IOS_APP_ID,
         vibesAppEnv: process.env.VIBES_APP_ENV || "UAT",
         apsEnvironment: process.env.APP_ENV || "development", // or "production"

       },
     ],
   ],
 },
};

Setting Environment Variables for EAS Cloud Build

For EAS Cloud Build:

  • Set environment variables in the env section of your eas.json file, referencing secrets using $ANDROID_APP_ID, $IOS_APP_ID, $APP_URL, and $VIBES_APP_ENV (recommended and most secure).
  • Set secrets using the eas secret:create command.
  • Do not rely on local .env files for cloud builds – they are ignored by EAS Cloud Build.
Setting EAS Secrets

Set secrets in Expo/EAS Cloud:

eas secret:create --name ANDROID_APP_ID --value your-android-app-id
eas secret:create --name IOS_APP_ID --value your-ios-app-id
eas secret:create --name APP_URL --value https://your-api-url.com/mobile_apps
eas secret:create --name VIBES_APP_ENV --value UAT # or PROD
eas secret:create --name APP_ENV --value development # or "production"

Best practice: Always test your cloud build to ensure variables are passed correctly to your plugin and app config.

4. Configure EAS Build

Create or update your eas.json file to include development builds:

{
 "cli": {
   "version": ">= 5.9.1"
 },
 "build": {
   "development": {
     "developmentClient": true,
     "distribution": "internal",
     "android": {
       "gradleCommand": ":app:assembleDebug"
     },
     "ios": {
       "buildConfiguration": "Debug",
       //In case you're having eas build cache issue - add these two
        "credentialsSource": "remote",
        "cache": {
          "key": "pods-ios-{{ hash }}"
        }
     },
     "env": {
       "ANDROID_APP_ID": "$ANDROID_APP_ID",
       "IOS_APP_ID": "$IOS_APP_ID",
       "APP_URL": "$APP_URL",
       "VIBES_APP_ENV": "$VIBES_APP_ENV",
       "APP_ENV": "$APP_ENV"
     }
   },
   "preview": {
     "distribution": "internal",
     "android": { 
       "buildType": "apk"
     },
     "ios": {
       "buildConfiguration": "Release"
     },
     "env": {
       "ANDROID_APP_ID": "$ANDROID_APP_ID",
       "IOS_APP_ID": "$IOS_APP_ID",
       "APP_URL": "$APP_URL",
       "VIBES_APP_ENV": "$VIBES_APP_ENV",
       "APP_ENV": "$APP_ENV"
     }
   },
   "production": {
     "android": {
       "buildType": "aab"
     },
     "ios": {
       "buildConfiguration": "Release"
     },
     "env": {
       "ANDROID_APP_ID": "$ANDROID_APP_ID",
       "IOS_APP_ID": "$IOS_APP_ID",
       "APP_URL": "$APP_URL",
       "VIBES_APP_ENV": "$VIBES_APP_ENV",
       "APP_ENV": "$APP_ENV"
     }
   }
 },
 "submit": {
   "production": {}
 }
}

5. Create Development Build

Build a custom development client that includes the Vibes SDK:

# For cloud build (recommended)
eas build --profile development --platform android
# For iOS development build
eas build --profile development --platform ios

This will:

  • Create a custom development client with Vibes SDK included
  • Apply the plugin configuration automatically
  • Generate an APK file (Android) or IPA file (iOS) you can install on your device

Android Configuration Details

Automatic Configuration

The plugin automatically configures the native Android files during the EAS build process. You don't need to manually edit these files:

AndroidManifest.xml

The plugin automatically adds these permissions and metadata:

<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.VIBRATE"/>
<!-- ... other permissions -->


<application>
 <meta-data android:name="vibes_app_id" android:value="${vibesAppId}"/>
 <meta-data android:name="vibes_api_url" android:value="${vibesAppUrl}"/>
 <!-- ... other metadata -->
</application>

build.gradle

The plugin automatically adds manifest placeholders:

android {
 defaultConfig {
   manifestPlaceholders = [
     vibesAppId: "your-app-id",
     vibesAppUrl: "your-api-url"
   ]
 }
}

iOS Configuration Details

Automatic Configuration

The plugin automatically configures the native iOS files during the EAS build process:

Info.plist

The plugin automatically adds these keys:

<key>VibesAppId</key>
<string>$(VIBES_APP_ID)</string>
<key>VibesApiURL</key>
<string>$(VIBES_API_URL)</string>
<key>VibesAppEnv</key>
<string>$(VIBES_APP_ENV)</string>

<key>NSPushNotificationsUsageDescription</key>
<string>This app uses push notifications to keep you updated.</string>
<key>UIBackgroundModes</key>
<array>
  <string>remote-notification</string>
</array>

AppDelegate.mm

The plugin automatically creates and configures AppDelegate.mm with Vibes SDK initialization and push notification handling.

VibesBridge Files

The plugin automatically creates:

  • VibesBridge.h - Header file for native bridge
  • VibesBridge.m - Implementation file for native bridge with push notification setup

Push Notifications

The plugin automatically adds:

  • Push notification permissions (NSPushNotificationsUsageDescription)
  • Background modes for remote notifications (UIBackgroundModes)
  • Entitlements for push notifications (aps-environment)
  • Automatic push token handling in AppDelegate.mm

Updated about 18 hours ago