Monitoring mobile applications

Requirements

• iOS 11 or later
• swift 5.1 or later

Swift Package Manager

1. Open Xcode.
2. Select File -> Swift Packages -> Add Package Dependency -> Your Xcode project.
3. Enter the https://github.com/instana/iOSAgent repository.

CocoaPods

1. Within your Podfile specification, add the commands:

   pod 'InstanaAgent'
   

2. To download the dependencies, run pod install.

Setup

For more information about the setup process, see the iOS agent API.

Requirements

• Android 4.1+ (API level 16+)
• Java 8+
• Gradle 7.3.3+
• AndroidX
• targetSdk 33+

Note: To use a Gradle version lower than 7.3.3 in your project, use an android-agent version lower than 6.0.0.

Instana Android plug-in

In your project-level build.gradle file, add the following code:

buildscript {
   repositories {
        google()
        mavenCentral()
    }
   dependencies {
      classpath "com.instana:android-agent-plugin:6.0.0"
    }
}

In your module (app-level) Gradle file (usually app/build.gradle) after you apply the com.android.application plug-in, add the following code:

apply plugin: 'com.android.application'
apply plugin: 'com.instana.android-agent-plugin'

Instana Android SDK

In your project-level build.gradle file, add the following code:

allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

In your module (app-level) Gradle file (usually app/build.gradle), add the following code:

dependencies {
    implementation 'com.instana:android-agent-runtime:6.0.0'
}

Java 1.8 compatibility

Note: Complete this step if your minSdkVersion is lower than 24.

In your module (app-level) Gradle file (usually app/build.gradle), add the following code:

android {
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

Request READ_PHONE_STATE permission (optional)

When a user accesses the internet through a cellular network, the Instana agent can report the specific type of cellular network.

To enable reporting of the cellular network type, your app needs to request the READ_PHONE_STATE permission. For more information about requesting permissions, see the Request App Permissions section in the official Android documentation.

If your app doesn't request the permission or if the user declines the permission, the Instana agent does not report the cellular network type.

Basic initialization

In your class, which extends Application, replace YOUR_REPORTING_URL and YOUR_APP_KEY with the configuration values you find in your Instana Dashboard:

class MyApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Instana.setup(
            this,
            InstanaConfig(
                key = "YOUR_APP_KEY",
                reportingURL = "YOUR_REPORTING_URL"
            )
        )
    }
}

Advanced usage

For a complete list of initialization options, view tracking, and other options, see the Android agent API.

Requirements

See Instana React Native Agent.

Add the dependency

Run the following command in your project's root:

npm install @instana/react-native-agent --save

Basic initialization

In your class App.js file, replace YOUR_INSTANA_APP_KEY and YOUR_INSTANA_REPORTING_URL with the configuration values you find in your Instana Dashboard:

export default class App extends Component {
  componentDidMount() {
    Instana.setup(YOUR_INSTANA_APP_KEY, YOUR_INSTANA_REPORTING_URL, null);
  }
}

Recommendation

To prevent the Instana agent tracing communication with the Metro bundler, add http://localhost:8081 to the ignored URLs list:

Instana.setIgnoreURLsByRegex(['http://localhost:8081.*']);

iOS

Your project should contain at least one Swift file (it can be empty).

If you don't have any Swift files, open your Xcode Project in <YourReactNativeProject>/ios then add an empty Swift file. Let Xcode create the Bridging Header for you.

Android

Use the Instana Android plug-in version appropriate for your React Native version:

• React Native 0.63.3 or earlier: Use Instana Android plug-in 1.5.3
• React Native 0.63.4 or later: Use Instana Android plug-in 5.2.2

Follow these steps to enable automatic HTTP monitoring:

1. In your /android/build.gradle file, add the following code:

   buildscript {
       dependencies {
           classpath "com.instana:android-agent-plugin:$INSTANA_ANDROID_PLUGIN_VERSION"
       }
   }
   

2. In your /android/app/build.gradle file, add the following code:

   apply plugin: 'com.android.application'
   apply plugin: 'com.instana.android-agent-plugin'
   

dependencies {
    implementation "com.squareup.okhttp3:okhttp:4.3.1"
    implementation "com.squareup.okhttp3:okhttp-urlconnection:4.3.1"
}

Advanced usage

For a complete list of initialization options, view tracking, and other options, see the React Native agent API.

Requirements

• Flutter version 1.20.0 or later
• Dart version between 2.12.0 and 3.0.0

Adding the package to your app

The Instana agent Flutter package is available from pub.dev.

To add the package to your app, complete the following steps:

1. Open the pubspec.yaml file located inside the app folder, and then add instana_agent: under dependencies.

2. Install the package, by using one of the following methods:

   • From the console: Run flutter pub get
   • From Android Studio or IntelliJ: Click Packages get in the action ribbon of pubspec.yaml
   • From VS Code: Click Get Packages in the action ribbon ofpubspec.yaml

Initialization

Import the package in your dart files:

import 'package:instana_agent/instana_agent.dart';

Stop and restart the app, if necessary.

Set up Instana as soon as possible. For example, in initState(), add the following code:

@override
  void initState() {
    super.initState();
    InstanaAgent.setup(key: 'YOUR-INSTANA-KEY', reportingUrl: 'YOUR-REPORTING_URL');
  }

If you intend to build for iOS, set up a minimum platform version in ${appFolder}/ios/Podspec with a minimum value of 11.0.

Tracing View changes

At any point after initializing the Instana agent, add InstanaAgent.setView('Home');:

import 'package:instana_agent/instana_agent.dart';

[...]

InstanaAgent.setView('Home');

Tracing HTTP requests

At any point after initializing Instana agent, start the capture of HTTP requests:

import 'package:instana_agent/instana_agent.dart';

[...]

InstanaAgent.startCapture(url: 'https://example.com/success', method: 'GET').then((marker) => marker
    ..responseStatusCode = 200
    ..responseSizeBody = 1000
    ..responseSizeBodyDecoded = 2400
    ..finish());

Create your own InstrumentedHttpClient extending http.BaseClient as shown in the following example:

class _InstrumentedHttpClient extends BaseClient {
   _InstrumentedHttpClient(this._inner);

   final Client _inner;

   @override
   Future<StreamedResponse> send(BaseRequest request) async {
      final Marker marker = await InstanaAgent.startCapture(url: request.url.toString(), method: request.method);

      StreamedResponse response;
      try {
         response = await _inner.send(request);
         marker
            ..responseStatusCode = response.statusCode
            ..responseSizeBody = response.contentLength
            ..backendTracingID = BackendTracingIDParser.fromHeadersMap(response.headers);
      } finally {
         await marker.finish();
      }

      return response;
   }
}

class _MyAppState extends State<MyApp> {

   [...]

   Future<void> httpRequest() async {
      final _InstrumentedHttpClient httpClient = _InstrumentedHttpClient(Client());
      final Request request = Request("GET", Uri.parse("https://www.instana.com"));
      httpClient.send(request);
   }

   [...]
}