• Acoustic Connect. To use the Connect SDK, your company must have an active Connect subscription of the Premium or Ultimate level. Proper credentials are required for each app (see Generate Connect credentials for integration).
• Development environment. You can integrate the Connect SDK into native iOS applications build on Swift and Objective-C. You will need Xcode 15 with Command Line Tools.
• Mobile app compatibility. The library can capture user experience data on end users' devices running iOS 13 and later. On iPadOS, only single-window applications are supported.

🚧

Warning

We offer limited support for iPad apps with a multi-window architecture. The Connect SDK captures data from such apps and makes it available for analytics, but session replays may not work correctly.

• Acoustic Connect. To use the Connect SDK, your company must have an active Connect subscription of the Premium or Ultimate level. Proper credentials are required for each app (see Generate Connect credentials for integration).
• Development environment. To integrate the SDK into your app, you need a standard Flutter environment. Supported versions: 3.3.0 - 3.22.2.
• Mobile app compatibility. The Connect SDK can function on end users' devices running Android 5.0 (API level 21) - Android 14 (API level 34). Supported iOS versions - 13.0 and later.

• Acoustic Connect. To use the Connect SDK, your company must have an active Connect subscription of the Premium or Ultimate level. Proper credentials are required for each app (see Generate Connect credentials for integration).
• Development environment. To integrate the SDK into your app, you need a standard React Native environment. Supported versions: 0.72.6 and later. Only older JSC bridge architecture is supported. Expo applications are not supported unless they are ejected as native applications.
• Mobile app compatibility. The library can function on end users' devices running Android 5.0 (API level 21) - Android 14 (API level 34). Supported iOS versions - 13.0 and later.

1. Open the version catalog file (gradle/libs.versions.toml). Add Connect to the [versions] and [libraries] blocks.

[versions]
connect = "10.4.28"
[libraries]
connect = { module = "io.github.go-acoustic:connect", version.ref = "connect" }

2. In the app-level build file (build.gradle.kts), update the dependencies block to support the Connect library.

implementation(libs.connect)

3. Synchronize the project.
4. Open the main entry point of the app and add an import statement for ConnectWrapper (a function that wraps around the UI tree of your app).

import com.acoustic.connect.android.connectmod.composeui.ConnectComposeUI.Companion.ConnectWrapper

5. Customize the ConnectWrapper function for your app.

// Connect SDK Wrapper init with app key and post message URL
ConnectWrapper(
    navController = navController,
    appKey = "your_key",
    postMessageURL = "your_endpoint_url"
){

6. Integrate ConnectWrapper into navController. It is important that you place ConnectWrapper at the root level of your app's composition.

ConnectWrapper integration examples

There are different ways to integrate ConnectWrapper with your navigation setup. Choose the approach that best fits the app architecture.

If your app uses a direct navigation controller, add the ConnectWrapper function right after you call rememberNavController(). The app content must be inside. For example, Google's official Sunflower app that we use for demo purposes has a direct navigation controller.

@Composable
fun YourApp() {
    val navController = rememberNavController()

    ConnectWrapper(
        navController = navController,
        appKey = "your_key",
        postMessageURL = "your_endpoint_url"
    ) {
        // Your app content
        YourNavHost(navController = navController)
    }
}

For better state management and testing, hoist navController to a state holder. Google's official Now in Android is an example of such an app.

class YourAppState(val navController: NavHostController) {
    // Other state management...
}

@Composable
fun rememberYourAppState(navController: NavHostController = rememberNavController()): YourAppState {
    return remember(navController) { YourAppState(navController) }
}

@Composable
fun YourApp() {
    val appState = rememberYourAppState()

    ConnectWrapper(
        navController = appState.navController,
        appKey = "your_key",
        postMessageURL = "your_endpoint_url"
    ) {
        // Your app content using appState
    }
}

If your app uses multiple navigation graphs, use the following approach.

@Composable
fun YourApp() {
    val navController = rememberNavController()

    ConnectWrapper(
        navController = navController,
        appKey = "your_key",
        postMessageURL = "your_endpoint_url"
    ) {
        NavHost(navController = navController, startDestination = "main") {
            // Your navigation graph
        }
    }
}

And here is a less typical example from an app with multiple back stack support.

@Composable
fun YourApp() {
    val navController = rememberNavController()
    // Configure back stack behavior
    val configuration =
        NavHostController.Configuration(
            navigatorProvider = navController.navigatorProvider,
            backStackBehavior = BackStackBehavior.MULTIPLE_BACK_STACKS
        )

    ConnectWrapper(
        navController = navController,
        appKey = "your_key",
        postMessageURL = "your_endpoint_url"
    ) {
        // Your multi-stack navigation
    }
}

📘

Note

Need a refresher? Here is an official article explaining Jetpack navigation - Define routes and create a NavHostController.

Option A: CocoaPods

You can add the Connect SDK to your iOS app using the CocoaPods dependency manager. This option requires a recent version of CocoaPods.

Here are steps to follow:

1. If you don't have a Podfile in your Xcode project directory, create one.
2. Open the Podfile in a text editor and make sure the iOS version is 13.0 or later. Then uncomment use_frameworks!.
3. In the same Podfile, set pod to either AcousticConnect or AcousticConnectDebug, depending on the build you want to use.

source 'https://github.com/CocoaPods/Specs.git'
platform :ios, '13.0'

target 'SwiftUIMindBlowing' do
  use_frameworks!
  pod 'AcousticConnect'
end

4. In a terminal emulator, navigate to your project directory.
5. Install the pods. Make sure the command is completed with no errors. If you get an error, run the same command with the --verbose option and share the error log with our services team.

pod install

Important notes:

• Sometimes CocoaPods fails to load the latest version. So you may need to pull it using pod update.
• If you get a warning message after running pod install, see our help article Removing CocoaPods warnings during integration.

Option B: Swift Package

You can add the Connect iOS SDK as a Swift Package.

1. In your Xcode project, go to File > Add Package Dependencies.

2. Search for https://github.com/go-acoustic/Connect-SP . For the debug build, replace Connect-SP with ConnectDebug-SP. Never use both versions in the same project.

3. Select the target to add the library to.

Option C: Carthage

You can add the Connect iOS SDK to your app using the Carthage dependency manager.

1. Create a Cartfile in your Xcode project directory if you don't have one yet.

touch Cartfile

2. Open the Cartfile in a text editor and add the following lines for the release build. To add the debug build, update the file names: instead of EOCore.json use EOCoreDebug.json, instead of Tealeaf.json use TealeafDebug.json and instead of Connect.json use ConnectDebug.json.

binary "https://raw.githubusercontent.com/go-acoustic/EOCore/master/EOCore.json"
binary "https://raw.githubusercontent.com/go-acoustic/Tealeaf/master/Tealeaf.json"
binary "https://raw.githubusercontent.com/go-acoustic/Connect/master/Connect.json"

🚧

Warning

Never use the release and debug builds together in the same project.

3. From the main project directory, run the command carthage update --use-xcframeworks. Make sure it completes without errors.
4. In a file manager, navigate to /Carthage/Build inside your project directory and select all three bundles.

5. In your Xcode project, select the primary project target. Drag and drop the bundles to Frameworks, Libraries, and Embedded Content. Select Embed & Sign for each bundle.

6. Switch to the Build Phases tab and make sure all three appear under Embed Frameworks. If they don't, you will need to add them as frameworks.

7. Rebuild the project.

1. From the root project directory, run the following commands.

flutter pub add connect_flutter_plugin 
flutter pub get

2. Open lib/main.dart and add an import statement there:

import 'package:connect_flutter_plugin/connect_flutter_plugin.dart';

3. To wrap the Connect library over your app, add another statement to lib/main.dart. Replace FormApp with the name of your app.

runApp(Connect(child: const FormApp()));

4. In the same file, add the Connect Wrapper and Navigation Observer. It handles the app's navigation route changes and event logging.

Dart

navigatorObservers: [Connect.loggingNavigatorObserver],

5. Copy the Connect Automation CLI directory from $HOME/.pub-cache/hosted/pub.dev/connect_flutter_plugin-<version>/package/connect_cli to the root of your user directory.

6. Navigate to the connect_cli directory that you have just created and fetch dependencies for your project.

Shell

cd $HOME/connect_cli
flutter pub get

7. From the root project directory, run a Dart file.

Shell

cd <YOUR_PROJECT_PATH>
dart run $HOME/connect_cli/bin/connect_cli.dart

8. Install the pods in the iOS version of the SDK.

Shell

cd ios && pod install

You can use NPM or Yarn. Run either of the following commands from the root project directory. It will add the Connect library to the package.json in your React Native project.

NPM command:

npm i react-native-acoustic-connect

Yarn command:

yarn add react-native-acoustic-connect

After that, open ConnectConfig.json in the root project directory and update the AppKey and PostMessageUrl parameters in it.

1. Open the AppDelegate.m file in your project.
2. Add 2 import statements to the header.

@import Tealeaf;
@import Connect;

3. Add the following code to the didFinishLaunchingWithOptions function. Replace app_key and endpoint_url with your Connect credentials.

[[TLFApplicationHelper sharedInstance] enableTealeafFramework:@"app_key" withPostMessageUrl:@"endpoint_url"];

4. If you have installed the debug version, add three variables with the value of 1 to the project scheme: EODebug, CONNECT_DEBUG and TLF_DEBUG.

1. In the root project directory, open ConnectConfig.json and update the AppKey and PostMessageUrl parameters in it.
2. If necessary, update other parameters (the list is available below).

3. Navigate to the root project directory and run the Connect Command Line Tool.

cd <YOUR_PROJECT_PATH>
dart run $HOME/connect_cli/bin/connect_cli.dart

🚧

Important

Make sure you run this command each time after updating ConnectConfig.json.

Here is a full list of configuration parameters you may need during the initial installation.

If your project uses React Navigation 5, make the following changes to App.js (or another file that serves as the main component of your app). This is necessary for correct screen capturing.

1. Add an import statement for Connect.

import { Connect } from 'react-native-acoustic-connect';

2. Wrap the navigation container into <Connect>.

export default () => {
  const navigationRef = useRef();

  return (
    <Connect>
      <NavigationContainer ref={navigationRef}>
        <StackNav/>
      </NavigationContainer>
    </Connect>
  );
};

Here is a sample file for your reference.

If your React Native project doesn't use React Navigation, make the following changes to App.js (or another file that serves as the main component of your app). This is necessary for correct screen capturing.

1. Add an import statement for Connect.

import {NativeModules, findNodeHandle} from 'react-native';
const Connect = NativeModules.RNCxa;

2. Add Connect.setCurrentScreenName("HomePage");.

Here is an example:

import React, { Component } from "react";
import { Container, Header, Title, Content, Button, Left, Right, Body, Text } from "native-base";
import styles from "./styles";

// Add import
import {NativeModules, findNodeHandle} from 'react-native';
const Connect = NativeModules.RNCxa;

class Header1 extends Component {
 render() {
   Connect.setCurrentScreenName("HomePage");
   return (
     <Container style={styles.container}>
       <Header>
         <Left />
         <Body>
           <Title>Header</Title>
         </Body>
         <Right />
       </Header>

       <Content padder>
         <Button onPress={() => this.props.navigation.goBack()}>
           <Text>Back</Text>
         </Button>
       </Content>
     </Container>
   );
 }
}
export default Header1;