From 6b9c8b5ba61c55dc19a91ee19e4848ab701c6562 Mon Sep 17 00:00:00 2001 From: Jamie Lynch Date: Wed, 16 Oct 2024 11:28:19 +0100 Subject: [PATCH 1/2] docs: update docs --- README.md | 2 +- embrace/README.md | 226 +--------------------------------------------- 2 files changed, 2 insertions(+), 226 deletions(-) diff --git a/README.md b/README.md index 5278de1..803e3fa 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Embrace Flutter SDK -[See the embrace package readme for integration instructions.](embrace/README.md) +[See the embrace docs for integration instructions.](https://embrace.io/docs/flutter/integration/) In order to use the Embrace Flutter SDK, you will need to [create an account with Embrace](https://dash.embrace.io/) first. diff --git a/embrace/README.md b/embrace/README.md index bb1751d..4d02f6d 100644 --- a/embrace/README.md +++ b/embrace/README.md @@ -1,227 +1,3 @@ # Embrace SDK for Flutter -In addition to installing the SDK, you'll need to create an Embrace login to see data in our [dashboard](https://dash.embrace.io/). - -# Integration - -## Dart setup - -Add the Embrace package to your `pubspec.yaml`. - -```sh -flutter pub add embrace -``` - -Wrap the entire contents of your Dart’s main function in `Embrace.instance.start()`. It is essential to wrap the entire contents of `main()` if you want Embrace to capture Dart errors. - -```dart -Future main() async { - await Embrace.instance.start(() => runApp(const MyApp())); -} -``` - -Perform additional setup for Android & iOS as described below. - -## iOS setup - -Add the following to `AppDelegate.m`: - -```objective-c -#import AppDelegate.h -#import -@implementation AppDelegate -- (BOOL)application:(UIApplication *) application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions { -[[Embrace sharedInstance] startWithLaunchOptions:launchOptions framework:EMBAppFrameworkFlutter]; - /* - Initialize additional crash reporters and - any other libraries to track *after* Embrace, including - network libraries, 3rd party SDKs - */ - return YES; -} -@end -``` - -
- Swift version - -```swift -import UIKit -import Flutter -import Embrace - -@UIApplicationMain -@objc class AppDelegate: FlutterAppDelegate { -override func application( - _ application: UIApplication, - didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? -) -> Bool { - Embrace.sharedInstance().start(launchOptions: launchOptions, framework: EMBAppFramework.flutter) - /* - Initialize additional crash reporters and - any other libraries to track *after* Embrace, including - network libraries, 3rd party SDKs - */ - return super.application(application, didFinishLaunchingWithOptions: launchOptions) -} -} - -``` - -
- -On the Xcode Build Phase tab, add a new run script. You can find your 5-character app ID and API token in the Embrace dashboard: - -```sh -EMBRACE_ID=YOUR_APP_ID EMBRACE_TOKEN=YOUR_API_TOKEN "${PODS_ROOT}/EmbraceIO/run.sh" -``` - -Create the Embrace-Info.plist configuration file. You can find your 5-character app ID and API token in the Embrace dashboard: - -```xml - - - - - API_KEY - {YOUR_APP_ID} - CRASH_REPORT_ENABLED - - - -``` - -## Android setup - -In the root-level `build.gradle` Gradle file, add: - -```gradle -buildscript { - repositories { - mavenCentral() - google() - } - dependencies { - classpath "io.embrace:embrace-swazzler:${findProject(':embrace_android').properties['emb_android_sdk']}" - } -``` - -In the `app/build.gradle` Gradle file, add: - -```gradle -apply plugin 'com.android.application' -apply plugin 'embrace-swazzler' -``` - -In `app/src/main`, add a config file named `embrace-config.json`. You can find your 5-character app ID and API token in the Embrace dashboard: - -```json -{ - "app_id": "", - "api_token": "", - "ndk_enabled": true -} -``` - -In your custom Activity class like in `MyApplication.java`, add: - -```java -import io.embrace.android.embracesdk.Embrace; -import android.app.Application; - -public final class MyApplication extends Application { - @Override - public void onCreate() { - super.onCreate(); - Embrace.getInstance().start(this, false, Embrace.AppFramework.FLUTTER); - } -} -``` - -
- Kotlin version - -```kotlin -import android.os.Bundle -import io.embrace.android.embracesdk.Embrace -import io.flutter.embedding.android.FlutterActivity - -class MainActivity: FlutterActivity() { - - override fun onCreate(savedInstanceState: Bundle?) { - super.onCreate(savedInstanceState) - Embrace.getInstance().start(this, false, Embrace.AppFramework.FLUTTER) - } -} -``` - -
- -If you do not already have a custom `Application` class, create a new source file matching the previous step then edit your `AndroidManifest.xml` to use your new custom Application class. Make sure you edit `AndroidManifest.xml` under the main sourceSet as well as any under debug/other sourceSets: - -```xml - -``` - -## Verify Your Integration - -Build and run your app. The Embrace Dashboard will display the following session data: - -- Views and taps -- First-party and third-party network calls (200s, 4xx, 5xx, and connection errors) with timing and call sizes -- Low memory and out-of-memory -- CPU pegging -- Low power mode -- Connectivity (Wifi, cellular, and switches between them) -- Device information (OS version, device, disk usage) -- Crashes -- User terminations - -## Tracking navigation automatically - -The Embrace SDK can automatically log the start and end of a route by adding the `EmbraceNavigationObserver` to the navigator observers inside your app. - -```dart -MaterialApp( - initialRoute: '/page1', - home: const Page1(), - navigatorObservers: [EmbraceNavigationObserver()], -); -``` - -By default it uses the name in the route settings as the tracked view name. You can customize this by adding a custom `routeSettingsExtractor` method to `EmbraceNavigationObserver`. - -## Using in Flutter Tests - -You can verify calls to Embrace are correct in unit tests by mocking `Embrace` and setting `debugEmbraceOverride`. This will override `Embrace.instance` in your Flutter code so you are able to capture and verify any calls made to Embrace. - -```dart -import 'package:embrace/embrace.dart'; -import 'package:flutter/material.dart'; -import 'package:flutter_test/flutter_test.dart'; -import 'package:mocktail/mocktail.dart'; - -class MockEmbrace extends Mock implements Embrace {} - -void main() { - testWidgets('button press add breadcrumb in Embrace', (tester) async { - final mockEmbrace = MockEmbrace(); - debugEmbraceOverride = mockEmbrace; - - await tester.pumpWidget( - MaterialApp( - home: ElevatedButton( - onPressed: () { - Embrace.instance.addBreadcrumb('Button pressed'); - }, - child: const Text('Press Me!'), - ), - ), - ); - - await tester.tap(find.text('Press Me!')); - - verify(() => mockEmbrace.addBreadcrumb('Button pressed')).called(1); - }); -} -``` +A package that captures telemetry and sends it to Embrace. [Please see the embrace docs for integration instructions.](https://embrace.io/docs/flutter/integration/) From 397309735635d3b53d70dc8a90f160eb44925e31 Mon Sep 17 00:00:00 2001 From: Jamie Lynch Date: Thu, 17 Oct 2024 15:17:08 +0100 Subject: [PATCH 2/2] Update embrace/README.md Co-authored-by: Francisco Prieto --- embrace/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/embrace/README.md b/embrace/README.md index 4d02f6d..12b143c 100644 --- a/embrace/README.md +++ b/embrace/README.md @@ -1,3 +1,3 @@ # Embrace SDK for Flutter -A package that captures telemetry and sends it to Embrace. [Please see the embrace docs for integration instructions.](https://embrace.io/docs/flutter/integration/) +A package that captures telemetry and sends it to Embrace. [Please see the Embrace docs for integration instructions.](https://embrace.io/docs/flutter/integration/)