From 51f978c84020caed4e62de27a3b9dfeb0ff6fdf9 Mon Sep 17 00:00:00 2001 From: Harsh Bhikadia Date: Sun, 9 May 2021 12:20:44 +0530 Subject: [PATCH] doc(readme): added Getting Started section --- .all-contributorsrc | 1 + README.md | 91 +++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 89 insertions(+), 3 deletions(-) diff --git a/.all-contributorsrc b/.all-contributorsrc index c5b014c..7f6b4d3 100644 --- a/.all-contributorsrc +++ b/.all-contributorsrc @@ -16,6 +16,7 @@ "avatar_url": "https://avatars.githubusercontent.com/u/4963236?v=4", "profile": "https://bhikadia.com/", "contributions": [ + "ideas", "code" ] } diff --git a/README.md b/README.md index cf10278..fb60793 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,4 @@ + # receive_intent

@@ -39,10 +40,94 @@ ___Any contribution, idea, criticism or feedback is welcomed.___ - In general, if you want other apps to "start" your app, then this plugin can pass the `Intent` that "triggered" it to the flutter environment of the app. These `Intent` will give the app understanding of why the app was started. Check [Getting started](#getting-started) section to implement this. ## Getting started -TODO +#### Add `` to `AndroidMainfest.xml` +You need to add `` to `android/app/src/main/AndroidManifest.xml` file: +```xml + + + + + + + + + + + + + + +``` +In this example we want to receive Intent with `action` matching `RECEIVE_INTENT_EXAMPLE_ACTION` literal. This `` should be added to the `Activity` that extends `FlutterActivity` (for project generated from template it is `MainActivity`). +To read more about "Intent and Intent Filter", encourage you to check [official docs](https://developer.android.com/guide/components/intents-filters) from Android. +#### Recevie and handle Intent that launched the Activity in Flutter +Inside flutter code, you can call `ReceiveIntent.getInitialIntent()` to get the `Intent` that started the `Activity`: +```dart +import 'package:receive_intent/receive_intent.dart'; +// ... + + Future _initReceiveIntent() async { + // Platform messages may fail, so we use a try/catch PlatformException. + try { + final receivedIntent = await ReceiveIntent.getInitialIntent(); + // Validate receivedIntent and warn the user, if it is not correct, + // but keep in mind it could be `null` or "empty"(`receivedIntent.isNull`). + } on PlatformException { + // Handle exception + } + } + +// ... +``` +#### Listen for any new Intent while the Activity is already running +To listen to new `Intent` while the `Activity` is running, you can use the `ReceiveIntent.receivedIntentStream` stream: +```dart +import 'package:receive_intent/receive_intent.dart'; +// ... + StreamSubscription _sub; + + Future _initReceiveIntentit() async { + // ... check initialIntent + + // Attach a listener to the stream + _sub = ReceiveIntent.receivedIntentStream.listen((Intent? intent) { + // Validate receivedIntent and warn the user, if it is not correct, + }, onError: (err) { + // Handle exception + }); + + // NOTE: Don't forget to call _sub.cancel() in dispose() + } +// ... +``` +#### Send result to the calling Activity (Optional) +If the calling `Activty` has "started" this activity with `startActivityWithResult` then you can send back result to that activity when ready with `ReceiveIntent.setResult`: +```dart +import 'package:receive_intent/receive_intent.dart'; +// ... + + Future _setActivityResult() async { + // ... + await ReceiveIntent.setResult(kActivityResultOk, data: {"sum": 123}) + } +// ... +``` +You can read more about "Starting Activities and Getting Results" pattern, encourage you to check [official docs](https://developer.android.com/reference/android/app/Activity#starting-activities-and-getting-results) from Android. +Additionaly, in the case of activity started with `startActivityWithResult`, the `Intent` object will also have package name (`intent.fromPackageName`) and app signautres (`intent.fromSignatures`) of the calling activity. This could be used to validate the calling app, so that sensitive information is not given to unintendent apps. +#### Tools to test it +You can test this with either [`adb`](https://developer.android.com/studio/command-line/adb) or [Intent Test](https://play.google.com/store/apps/details?id=com.applauncher.applauncher) app form Playstore. +##### abd +To invoke (start) our `FlutterAcitivity` with `RECEIVE_INTENT_EXAMPLE_ACTION` intent action name as mentioned in example `` [above](#add-intent-filter-to-AndroidMainfest.xml): +```sh +adb shell 'am start -W -a RECEIVE_INTENT_EXAMPLE_ACTION -c android.intent.category.DEFAULT' +``` +If you don't have [`adb`](https://developer.android.com/studio/command-line/adb) in your path, but have `$ANDROID_HOME` env variable then use `"$ANDROID_HOME"/platform-tools/adb ...`. +Note: Alternatively you could simply enter an `adb shell` and run the [`am`](https://developer.android.com/studio/command-line/adb#am) commands in it. + +#### Check example app +To know more or to get the working code check the [example app](https://github.com/daadu/receive_intent/tree/master/example). ## Todo -- Write [Getting started](#getting-started) section - Document API references properly - Receive Intent for non-`Activity` based `intent-filter` (`BroadcastReceiver`, `Service`) - Automatic testing @@ -71,7 +156,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d - +

Harsh Bhikadia
💻
Harsh Bhikadia
🤔 💻