GuidesReference
Guides
BlogUpdatesSlackGitHubConsole

Install Mobile SDK

Install the Orb Mobile SDK in your mobile apps.

Suggest Edits

Prerequisites

Install the following prerequisites, depending on whether you'll be using the SDK for Android, iOS, or Flutter.

Install Android Studio (Android / Flutter)

Follow the Android Studio installation instructions for your development
environment:

Install Xcode (iOS / Flutter)

Follow the Xcode installation instructions for your development mac:

Install Flutter (Android / Flutter)

Follow the Flutter installation instructions for your development environment:

📘

Flutter v2.10.4

The Orb Mobile SDK is based Flutter v2.10.4, you will need to download v2.10.4 from the Flutter archive site:

Flutter v2.10.4 (Windows)

Flutter v2.10.4 (macOS)

Flutter v2.10.4 (Linux)

Check your Flutter installation:

which flutter
flutter doctor

Install Android Studio Flutter plugin (Android / Flutter)

We recommend using Android Studio to view and edit any Flutter app/package/plugin/module.

Follow the Flutter editor setup instructions for your development environment:

Open module in Android Studio (Android / Flutter)

  • Open Android Studio
  • Select Open an Existing Project
  • Navigate to the orb-sdk repo folder and select the module folder
  • Click Open

This will open the module Flutter project in Android Studio. The Flutter
plugin in Android Studio will do a couple of things:

  • Detect that it is a Flutter project and not an Android project.
  • Run flutter pub get: this will read the pubspec.yaml file and download
    all the Flutter dependencies.
  • Index all the Dart source code.
  • Detect any running Android/iOS/Web devices

Run the module (Flutter)

A Flutter module is not intended to be run on it's own, it's primary purpose is to integrate
the Flutter module into an existing native app. However, it is still possible to run a Flutter
module.

This is good to do initially to test that your Android and iOS environments work correctly
and that everything compiles.

Run on Android

If you do not have one already you need to setup an Android Virtual Device:

  • Go to Tools > AVD Manager
  • Click + Create Virtual Device at the bottom left
  • From the Phone category, select a device e.g. Pixel 3
  • Click Next
  • Use the recommended release (you can customize this if you wish).
  • Click Next
  • Optionally set the AVD Name
  • Click Finish
  • From the AVD Manager, click the "Play" button of the device you've just
    created.

Android Studio should automatically detect the AVD device and create a new run configuration for
the Android device.

  • In the device dropdown menu, select Refresh
  • Then select the AVD device you wish to target.
  • Make sure the main.dart run configuration is selected in the dropdown to the right of the
    device dropdown menu.
  • Click the "Play" button.

The Flutter plugin in Android Studio will now do a couple of things:

  • It will run all the Gradle tasks to build and assemble the Android app
  • It will install the Debug APK onto the AVD via adb
  • It will launch the app on the AVD and connect the Flutter debugger

Min SDK version build error

If the Gradle build fails with the following error:

AndroidManifest.xml Error:
	uses-sdk:minSdkVersion 16 cannot be smaller than version 18 declared in library [:orb] 
...
	Suggestion: use a compatible library with a minSdk of at most 16,
		or increase this project's minSdk version to at least 18,
		or use tools:overrideLibrary="ai.meya.orb" to force usage (may lead to runtime failures)

Then manually edit the generated Gradle build file:

  • Open .android/app/build.gradle
  • Change the line minSdkVersion 16 to minSdkVersion 18
  • Save the change
  • Click the "Play" button again

You should see a screen saying Ready to connect.

Run on iOS

  • In the device dropdown menu, select Open iOS Simulator
  • This will launch the iOS Simulator
  • In the iOS Simulator, go to File > Open Simulator > iOS 14.4 > iPhone 11
  • This will open the iPhone simulator
  • Once the simulator is running, Android Studio will detect the new device
  • In the device dropdown menu, select the iPhone 11 (mobile) device
  • Make sure the main.dart run configuration is selected in the dropdown to the right of the
    device dropdown menu.
  • Click the "Play" button.

The Flutter plugin in Android Studio will now do a couple of things:

  • It will run pod install and collect all the Cocoapod dependencies
  • It will build the iOS app using XCode
  • It will copy over the app bundle to the iPhone simulator and install the app
  • It will connect the Flutter debugger

You should see a screen saying Ready to connect.

Add to an Android app

Project setup

In your terminal:

  • Go to the module folder:
    cd some/path/module
  • Run: flutter build aar
  • This will build various AAR packages and create a local Gradle repository.
  • Open your app's app/build.gradle file
  • Ensure you have the following repositories configured: 
    String storageUrl = System.env.FLUTTER_STORAGE_BASE_URL ?: "https://storage.googleapis.com"
repositories {
    maven {
        url projectDir.absolutePath + '/some/relative/path/module/build/host/outputs/repo'
    }
    maven {
        url "$storageUrl/download.flutter.io"
    }
}
  • Make the app depend on the Flutter module 
    dependencies {
    debugImplementation 'ai.meya.orb_module:flutter_debug:1.0'
    profileImplementation 'ai.meya.orb_module:flutter_profile:1.0'
    releaseImplementation 'ai.meya.orb_module:flutter_release:1.0'
}
  • Add the profile build type to your android.buildTypes e.g.: 
    android {
  buildTypes {
    profile {
      initWith debug
    }
  }
}
  • Sync your build.gradle changes

For extra information on adding Flutter modules to Android, view the
Add to Android app Flutter documentation

Add and launch the ChatActivity

  • Create a ChatActivity class in your app.
  • Example Orb Demo ChatActivity
  • The Orb SDK provides an OrbActivity class to initialize, connect and
    display the Orb in a full screen view.
  • Make sure to set your Meya App ID in the OrbConnectionOptions.
    Note, the pageContext is an arbitrary Map<String, Object> object that
    you can use to send custom context data to your bot when the Orb connects.
  • Add the ChatActivity to your AndroidManifest.xml file, see the
    example Orb Demo AndroidManifest.xml file

🚧

Note

Make sure the android:name has the correct class path to where you created the ChatActivity file.

Also add the following permissions to allow Orb access to the photo gallery, camera and to open URLs:

<uses-permission android:name="android.permission.CAMERA" />
<queries>
    <intent>
        <action android:name="android.media.action.IMAGE_CAPTURE" />
    </intent>
      <intent>
          <action android:name="android.intent.action.VIEW" />
          <data android:scheme="https" />
      </intent>
      <!-- If your app makes calls -->
      <intent>
          <action android:name="android.intent.action.DIAL" />
          <data android:scheme="tel" />
      </intent>
      <!-- If your app emails -->
      <intent>
          <action android:name="android.intent.action.SEND" />
          <data android:mimeType="*/*" />
      </intent>
</queries>
  • Start ChatActivity: 
    myChatButton.setOnClickListener(new View.OnClickListener() {
    @Override
    public void onClick(View view) {
        startActivity(
            ChatActivity.createDefaultIntent(getBaseContext(), ChatActivity.class)
        );
    }
});

Add to an iOS app

Add to an iOS app using the Orb Cocoapod

If you're using Cocoapods for dependency management, or you want to integrate
Orb quickly then it's very easy to add Orb to your project.

Project setup

Requirements:

  • CocoaPods v1.10 or later.
  • XCode 12.5
  • Swift 5

If your existing iOS app doesn't already have a Podfile, follow the
CocoaPods getting started guide
to add a Podfile to your project.

  • Add the following to your Podfile:
    pod 'Orb', '2.7.9', :source => 'https://github.com/meya-customers/orb-cocoapods'

  • Your Podfile should like something like this:

    platform :ios, '9.0'

target 'OrbDemo' do
    use_frameworks!
    pod 'Orb', '2.7.9', :source => 'https://github.com/meya-customers/orb-cocoapods'
end

  • Run pod install

  • Note: if you would like to use the Orb in the iOS simulator, then you need to install the OrbDebug pod instead of the Orb pod. The version numbers are the same.

Add to an iOS app using the orb-sdk/module Flutter module

This method of integration is very useful for development purposes because it
allows you to run the Orb Flutter code in debug mode, and allows you to make
Dart code changes.

🚧

Bitcode

Currently you will need to disable bitcode for your app. If you
need bitcode enabled, then we recommend using the pre-compiled Orb Cocoapod.

Project setup

Requirements:

If your existing iOS app doesn't already have a Podfile, follow the
CocoaPods getting started guide
to add a Podfile to your project.

  • Add the following to your Podfile:

    orb_sdk_path = 'some/relative/path/module'
load File.join(orb_sdk_path, '.ios', 'Flutter', 'podhelper.rb')

  • For each Podfile target that needs to embed the Orb SDK, call
    install_all_flutter_pods(orb_sdk_path) e.g.:

    target `MyApp` do
    install_all_flutter_pods(orb_sdk_path)
end

  • Run pod install

📘

Updating

When you update the version of the module and/or orb, run
flutter pub get in the module folder to refresh the list of dependencies
read by podhelper.rb. Then, run pod install again for your application.

The podhelper.rb script embeds the module framework, Flutter.framework
and any transitive Flutter plugin dependencies into your project.

Open your apps .xcworkspace file in Xcode and build using Cmd+B.

Add and launch the Orb

  • Create the OrbInit.swift file in your app's code folder.
  • Example Orb Demo OrbInit.swift file
  • This code extends the Orb class to initialize the Flutter engine with the
    correct plugins and initializes internal callbacks between the Orb class
    and the OrbPlugin class.

The Orb SDK gives you a lot of flexibility in how to initialize and show the
Orb chat, but the simplest method is to simply create a new instance of Orb
and display it's ViewController in fullscreen mode.

📘

Page Context

pageContext is an arbitrary dictionary that you can use to send context data to your bot when the Orb connects.

Add to a Flutter app

To add the Orb SDK to a Flutter app, first you need to the dependency to your pubspec.yaml (using the path to the Orb SDK):

dependencies:
  orb:
    path: ../orb-sdk/orb

Then run flutter pub get to install.

Initialize plugins (iOS)

For iOS, you also need to make sure the Orb SDK plugins are initialized together with any other Flutter plugins you're currently using.

Configuration

You will need to set Orb config, theme, and connection options separately for Android and iOS.

Add the widget

Orb is its own MaterialApp, so you will not be able to nest it within your own. When the chat is active, build the OrbApp widget.

Updated over 1 year ago

What’s Next