feat(firebase_installations): initial Firebase Installations release (#…

…7377)

Co-authored-by: Mike Diarmid <mike.diarmid@gmail.com>
Co-authored-by: pr_Mais <hiimechi@gmail.com>
Co-authored-by: russellwheatley <russellwheatley85@gmail.com>

.github/workflows/firebase_installations.yaml

@@ -0,0 +1,80 @@
+name: firebase_installations
+
+on:
+  pull_request:
+    paths:
+      - 'packages/firebase_installations/**'
+      - '.github/workflows/firebase_installations.yaml'
+  push:
+    branches:
+      - master
+    paths-ignore:
+      - 'docs/**'
+      - '**.md'
+
+env:
+  FLUTTERFIRE_PLUGIN_SCOPE: '*installations*'
+  FLUTTERFIRE_PLUGIN_SCOPE_EXAMPLE: '*installations_example*'
+
+jobs:
+  android:
+    runs-on: macos-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v2.3.4
+        with:
+          fetch-depth: 0
+      - name: 'Install Flutter'
+        run: ./.github/workflows/scripts/install-flutter.sh stable
+      - name: 'Install Tools'
+        run: ./.github/workflows/scripts/install-tools.sh
+      - name: 'Build Example'
+        run: ./.github/workflows/scripts/build-example.sh android
+      - name: 'Drive Example'
+        uses: reactivecircus/android-emulator-runner@v2
+        with:
+          api-level: 28
+          arch: x86_64
+          # Firebase Core works without Google Play Services, so we don't use the `googleapis`
+          # emulator target as it's considerably slower on CI.
+          target: default
+          profile: Nexus 5X
+          script: ./.github/workflows/scripts/drive-example.sh android
+
+  apple:
+    runs-on: macos-latest
+    timeout-minutes: 35
+    steps:
+      - uses: actions/checkout@v2.3.4
+        with:
+          fetch-depth: 0
+      - name: 'Install Flutter'
+        run: ./.github/workflows/scripts/install-flutter.sh stable
+      - name: 'Install Tools'
+        run: |
+          ./.github/workflows/scripts/install-tools.sh
+          flutter config --enable-macos-desktop
+      - name: 'Build iOS Example'
+        run: ./.github/workflows/scripts/build-example.sh ios
+      - name: 'Drive iOS Example'
+        run: ./.github/workflows/scripts/drive-example.sh ios
+      - name: 'Build MacOS Example'
+        run: ./.github/workflows/scripts/build-example.sh macos
+      - name: 'Drive MacOS Example'
+        run: ./.github/workflows/scripts/drive-example.sh macos
+
+  web:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v2.3.4
+        with:
+          fetch-depth: 0
+      - name: 'Install Flutter'
+        run: ./.github/workflows/scripts/install-flutter.sh stable
+      - name: 'Install Tools'
+        run: |
+          ./.github/workflows/scripts/install-tools.sh
+          flutter config --enable-web
+      - name: 'Drive Example'
+        run: ./.github/workflows/scripts/drive-example.sh web

docs/installations/overview.mdx

@@ -0,0 +1,70 @@
+---
+title: Firebase Installations
+sidebar_label: Overview
+---
+
+## What does it do?
+
+Firebase Installations is a service that allows you to manage the installation of your app on a user's device.
+The Firebase installations service (FIS) provides a Firebase installation ID (FID) for each installed instance of a Firebase app.
+
+Internally, the installation ID is used by the following Firebase Services:
+
+- Firebase Cloud Messaging (FCM)
+- Firebase In-App Messaging (FIAM)
+- Firebase Performance Monitoring
+- Firebase Predictions
+- Google Analytics for Firebase
+- Firebase Remote Config
+- Firebase ML
+
+Typically, Firebase services use the Firebase installations service without requiring developers to interact directly with the FIS API. However, there are cases where app developers might want to directly call the FIS API, such as:
+
+- Delete a Firebase installation and data tied to the installation.
+- Retrieve identifiers (Firebase installation IDs) in order to target specific app installations.
+- Retrieve installation auth tokens to authenticate Firebase installations.
+
+## Installation
+
+Add the `flutterfire_installations` dependency to your projects `pubspec.yaml` file:
+
+```yaml {5} title="pubspec.yaml"
+dependencies:
+  flutter:
+    sdk: flutter
+  firebase_core: "^{{ plugins.firebase_core_ns }}"
+  flutterfire_installations: "^{{ plugins.flutterfire_installations_ns }}"
+```
+
+### 2. Download dependency
+
+```
+$ flutter pub get
+```
+
+### 3. (Web Only) Add the SDK
+
+If using FlutterFire on the web, add the `firebase-installations` JavaScript SDK to your `index.html` file:
+
+```html {5} title="web/index.html"
+<html>
+  ...
+  <body>
+    <script src="https://www.gstatic.com/firebasejs/{{ web.firebase_cdn }}/firebase-app.js"></script>
+    <script src="https://www.gstatic.com/firebasejs/{{ web.firebase_cdn }}/firebase-installations.js"></script>
+  </body>
+</html>
+```
+
+### 4. Rebuild your app
+
+Once complete, rebuild your Flutter application:
+
+```bash
+$ flutter run
+```
+
+## Next Steps
+
+Once installed, you're ready to start using Firebase Installations in your Flutter Project. View the
+[Usage documentation](./usage.mdx) to get started.

docs/installations/usage.mdx

@@ -0,0 +1,108 @@
+---
+title: Firebase Installations
+sidebar_label: Usage
+---
+
+To start using the Firebase Installations package within your project, import it at the top of your project files:
+
+```dart
+import 'package:flutterfire_installations/flutterfire_installations.dart';
+```
+
+Before using Firebase Installations, you must first have ensured you have [initialized FlutterFire](../overview.mdx#initializing-flutterfire).
+
+To create a new Installations instance, call the [`instance`](!firebase_installations.FirebaseInstallations.instance) getter on
+[`FirebaseInstallations`](!firebase_installations.FirebaseInstallations):
+
+```dart
+FirebaseInstallations installations = FirebaseInstallations.instance;
+```
+
+By default, this allows you to interact with Installations using the default Firebase App used whilst installing
+FlutterFire on your platform. If however you'd like to use a secondary Firebase App, use the `instanceFor` method:
+
+```dart
+FirebaseApp secondaryApp = Firebase.app('SecondaryApp');
+FirebaseInstallations installations = FirebaseInstallations.instanceFor(app: secondaryApp);
+```
+
+## Delete a Firebase installation
+
+Data tied to a Firebase installation is generally not personally identifying. Still, it can be helpful to give users an option to manage and delete this data.
+
+Firebase installation IDs are different for every installation of every application; different applications on the same device have different Firebase installation IDs.
+Firebase installation IDs identify app installations and data tied to those app installations.
+
+When you delete an installation ID, the data tied to that installation ID is removed from live and backup systems of all Firebase services that use Firebase installation
+IDs to identify installations within 180 days. This process is described at a high level in Google’s [statement on deletion and retention](https://policies.google.com/technologies/retention).
+
+Unless you disable all FID-generating services in your app, FIS creates a new ID within a few days. Firebase considers the newly-created ID to be a new Firebase installation,
+and doesn't associate it with the previous ID or data in any way.
+
+To delete an FID, call the `delete` method on the [`FirebaseInstallations`](!firebase_installations.FirebaseInstallations) instance:
+
+```dart
+await FirebaseInstallations.instance.delete();
+```
+
+## Retrieve client identifiers
+
+If you have a requirement to identify particular installations of your app, you can do so by retrieving the Firebase installation ID. 
+For example, to perform testing during Firebase In-App Messaging development, you can identify and target the correct test device using
+its Firebase installation ID.
+
+To get the Firebase installation ID, call the `getId` method on the [`FirebaseInstallations`](!firebase_installations.FirebaseInstallations) instance:
+
+```dart
+String id = await FirebaseInstallations.instance.getId();
+```
+
+## Retrieve installation auth tokens
+
+Firebase services can authenticate Firebase installations with auth tokens retrieved from FIS. For example, when designing A/B tests for Remote Config,
+you can authenticate a targeted test device using an installation auth token.
+
+An installation auth token is a short-lived bearer token in JSON web token (JWT) format containing the following information for an installation:
+
+- The Firebase installation ID
+- The associated project (`projectNumber`)
+- The associated Firebase application ID (`appId`)
+- The token's expiration date
+
+An installation auth token cannot be revoked, and remains valid until its expiration date. The default token lifetime is one week.
+
+To retrieve an installation auth token:
+
+```dart
+String token = await FirebaseInstallations.instance.getToken();
+```
+
+Optionally, you can force a token refresh when called:
+
+```dart
+String token = await FirebaseInstallations.instance.getToken(true);
+```
+
+## Monitor the Firebase Installation ID
+
+During the normal operation of an app, Firebase installation IDs (FIDs) don't require special monitoring. However, apps that explicitly retrieve and
+use FIDs should add logic to monitor the potential deletion or rotation of the FID. Here are some cases where FIDs could be deleted or rotated:
+
+- Uninstallation or re-installation of the app, for instance when an end user installs on a new device.
+- The end user clears the cache of the app or the device.
+- FID deletion is triggered in the backend due to app inactivity (currently the threshold for this is 270 days of inactivity).
+
+When apps experience a FID rotation or deletion in these kinds of cases, they are assigned a new FID. Also, the installation auth token associated with
+a deleted FID is deleted, regardless of its own maturity, and is replaced with a new installation auth token.
+
+Apps can monitor these changes and respond accordingly.
+
+To monitor the FID token, listen to the `Stream` returned from the `onIdChange` getter:
+
+```dart
+FirebaseInstallations.instance.onIdChange.listen((token) {
+  print('FID token: $token');
+});
+```
+
+

docs/sidebars.js

@@ -67,6 +67,10 @@ module.exports = {
       toReferenceAPI("cloud_functions"),
       toGithubExample("cloud_functions"),
     ],
+    Installations: [
+      "installations/overview",
+      "installations/usage",
+    ],
     "Cloud Messaging": [
       "messaging/overview",
       "messaging/usage",

docs/versions.js

@@ -31,6 +31,7 @@ export default {
     firebase_performance_ns: PUB_NS_FIREBASE_PERFORMANCE,
     firebase_remote_config: PUB_FIREBASE_REMOTE_CONFIG,
     firebase_remote_config_ns: PUB_NS_FIREBASE_REMOTE_CONFIG,
+    flutterfire_installations: PUB_NS_FLUTTERFIRE_INSTALLATIONS,
     firebase_ml_model_downloader_ns: PUB_NS_FIREBASE_ML_MODEL_DOWNLOADER,
     google_sign_in: "^4.4.4",
   },

packages/firebase_core/firebase_core_web/lib/src/firebase_core_web.dart

@@ -157,6 +157,8 @@ class FirebaseCoreWeb extends FirebasePlatform {
               'https://www.gstatic.com/firebasejs/$version/firebase-remote-config',
           '@firebase/performance':
               'https://www.gstatic.com/firebasejs/$version/firebase-performance',
+          '@firebase/installations':
+              'https://www.gstatic.com/firebasejs/$version/firebase-installations',
         },
       })
     ]);

packages/firebase_installations/firebase_installations/.gitignore

@@ -0,0 +1,7 @@
+.DS_Store
+.dart_tool/
+
+.packages
+.pub/
+
+build/

packages/firebase_installations/firebase_installations/.metadata

@@ -0,0 +1,10 @@
+# This file tracks properties of this Flutter project.
+# Used by Flutter tool to assess capabilities and perform upgrades etc.
+#
+# This file should be version controlled and should not be manually edited.
+
+version:
+  revision: 18116933e77adc82f80866c928266a5b4f1ed645
+  channel: stable
+
+project_type: plugin

packages/firebase_installations/firebase_installations/CHANGELOG.md

@@ -0,0 +1,3 @@
+## 0.1.0
+
+ - Initial release of the Firebase Installations plugin.

packages/firebase_installations/firebase_installations/LICENSE

@@ -0,0 +1,27 @@
+// Copyright 2021 The Chromium Authors. All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+//    * Redistributions of source code must retain the above copyright
+// notice, this list of conditions and the following disclaimer.
+//    * Redistributions in binary form must reproduce the above
+// copyright notice, this list of conditions and the following disclaimer
+// in the documentation and/or other materials provided with the
+// distribution.
+//    * Neither the name of Google Inc. nor the names of its
+// contributors may be used to endorse or promote products derived from
+// this software without specific prior written permission.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

packages/firebase_installations/firebase_installations/README.md

@@ -0,0 +1,23 @@
+# Firebase Installations Plugin for Flutter
+
+A Flutter plugin to use the [Firebase Installations API](https://firebase.google.com/docs/projects/manage-installations).
+
+[![pub package](https://img.shields.io/pub/v/flutterfire_installations.svg)](https://pub.dev/packages/flutterfire_installations)
+
+## Getting Started
+
+To get started with Firebase Installations for Flutter, please [see the documentation](https://firebase.flutter.dev/docs/installations/overview).
+
+## Usage
+
+To use this plugin, please visit the [Installations Usage documentation](https://firebase.flutter.dev/docs/installations/usage)
+
+## Issues and feedback
+
+Please file FlutterFire specific issues, bugs, or feature requests in our [issue tracker](https://github.com/FirebaseExtended/flutterfire/issues/new).
+
+Plugin issues that are not specific to FlutterFire can be filed in the [Flutter issue tracker](https://github.com/flutter/flutter/issues/new).
+
+To contribute a change to this plugin,
+please review our [contribution guide](https://github.com/FirebaseExtended/flutterfire/blob/master/CONTRIBUTING.md)
+and open a [pull request](https://github.com/FirebaseExtended/flutterfire/pulls).

packages/firebase_installations/firebase_installations/android/.gitignore

@@ -0,0 +1,8 @@
+*.iml
+.gradle
+/local.properties
+/.idea/workspace.xml
+/.idea/libraries
+.DS_Store
+/build
+/captures