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:

Windows/macOS/Linux/ChromeOs

Install Xcode (iOS / Flutter)

Follow the Xcode installation instructions for your development mac:

macOS

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:

Windows/macOs/Linux

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

🚧
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:

CocoaPods v1.10 or later.

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.

Create a button and an @IBAction handler
Example Orb Demo @IBAction handler
Set your Meya App ID in the OrbConnectionOptions.

📘
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.

Example Orb Demo code

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.

Example Orb Demo code