[master] fixed some typos. fitbitter 2.0.1

gcappon · Sep 7, 2022 · 3e81b23 · 3e81b23
1 parent 15e4bee
commit 3e81b23
Show file tree

Hide file tree

Showing 15 changed files with 221 additions and 111 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,7 @@
+## [2.0.1] - 2022/09/06
+
+Fixed some typos.
+
 ## [2.0.0] - 2022/09/06
 
 Major release 2.0.0. 

diff --git a/README.md b/README.md
@@ -4,8 +4,172 @@
 
 A Flutter package to make your life easier when dealing with Fitbit APIs.
 
+## Getting started 
+
+### Step 1: Install Fitbitter
+
+To install Fitbitter, simply add `fitbitter: ` to the dependencies of your `pubspec.yaml` file: 
+
+```yaml
+dependencies:
+    fitbitter: #latest version
+```
+
+### Step 1a: (for Android only) Modify you manifest
+
+Fitbitter uses `flutter_web_auth` to let you authenticate to Fitbit. In Android, you need to add these lines of code to your `android/app/src/main/AndroidManifest.xml` file:
+```xml
+<activity android:name="com.linusu.flutter_web_auth.CallbackActivity" >
+      <intent-filter android:label="flutter_web_auth">
+        <action android:name="android.intent.action.VIEW" />
+        <category android:name="android.intent.category.DEFAULT" />
+        <category android:name="android.intent.category.BROWSABLE" />
+        <data android:scheme="CALLBACK_SCHEME" />
+      </intent-filter>
+    </activity>
+```
+and change ```CALLBACK_SCHEME``` with your callback scheme (in the test example below this will be ```example```)
+
+### Step 1b: (for Android only) Increase the minimum Android SDK version
+
+Fitbitter uses `flutter_secure_storage` to securely store the Fitbit tokens. Since `flutter_secure_storage` requires that minimum Android SDK version is 18, you need to change the default minimum sdk version to 18 or above. To do so, open `android/app/build.gradle`, locate this snippet of code:
+```gradle
+...
+defaultConfig {
+        applicationId "your.app.id"
+        minSdkVersion flutter.minSdkVersion
+        targetSdkVersion flutter.targetSdkVersion
+        versionCode flutterVersionCode.toInteger()
+        versionName flutterVersionName
+    }
+...
+```
+and change ```minSdkVersion``` to 18 or above, e.g.,:
+```gradle
+...
+defaultConfig {
+        applicationId "your.app.id"
+        minSdkVersion 18
+        targetSdkVersion flutter.targetSdkVersion
+        versionCode flutterVersionCode.toInteger()
+        versionName flutterVersionName
+    }
+...
+```
+
+### Step 1c: (for Android only) Requirement: Web Browser
+
+Fitbitter uses `flutter_web_auth` to let you authenticate to Fitbit. In order to let it work correcty please be sure that your emulator or your physical device is using Chrome, Opera, or Firefox as default web browser. 
+
+### Step 1d:(for Web only) Requirement: Create an endpoint
+
+Fitbitter uses `flutter_web_auth` to let you authenticate to Fitbit. In order to let it work correcty, as indicated in [https://pub.dev/packages/flutter_web_auth](https://pub.dev/packages/flutter_web_auth), on the Web platform an endpoint needs to be created that captures the callback URL and sends it to the application using the JavaScript `postMessage()` method. In the `./web` folder of the project, create an HTML file with the name e.g. `auth.html` with content:
+```html
+<!DOCTYPE html>
+<title>Authentication complete</title>
+<p>Authentication is complete. If this does not happen automatically, please
+close the window.
+<script>
+  window.opener.postMessage({
+    'flutter-web-auth': window.location.href
+  }, window.location.origin);
+  window.close();
+</script>
+```
+Redirection URL passed to the authentication service must be the same as the URL on which the application is running (schema, host, port if necessary) and the path must point to created HTML file, `/auth.html`in this case. The `callbackUrlScheme` parameter of the `authenticate()` method does not take into account, so it is possible to use a schema for native platforms in the code.
+
+For the Sign in with Apple in web_message response mode, postMessage from [https://appleid.apple.com](https://appleid.apple.com) is also captured, and the authorization object is returned as a URL fragment encoded as a query string (for compatibility with other providers).
+
+### Step 2: Test Fitbitter
+
+Once installed, it is time to test drive Fitbitter. In this example, we will use Fitbitter to authenticate our app into Fitbit APIs and simply fetch yesterday's step count. 
+
+#### Preliminary requirement: Register your app 
+
+To be able to perform any operation with the Fitbit APIs, you must register first your application in the developer portal of Fitbit and obtain two IDs, namely the "**OAuth 2.0 Client ID**" and the "**Client Secret**". To do so, you have to follow these steps. 
+
+* Create a Fitbit account, if you do not have one.
+* Register a new app at [https://dev.fitbit.com/apps/new](https://dev.fitbit.com/apps/new).
+  The form will look like this: 
+  ![Fitbit App Registration Form](https://github.com/gcappon/fitbitter/blob/gh-pages/fitbitAppRegistrationForm.png)
+
+* Choose an "Application Name" (e.g., "Example").
+* Set a brief "Description" (e.g., "Just a simple test of an awesome package.")
+* Set the "Application Website". It can be random for the purpose of testing the example so let's put https://www.example.com/.
+* Set an "Organization" (e.g., "Myself").
+* Set an "Organization Website". It can be random for the purpose of testing the example so let's put https://www.myself.com/.
+* Set a "Terms of Service Url". It can be random for the purpose of testing the example so let's put https://www.myself.com/tos.
+* Set an "Privacy Policy Url". It can be random for the purpose of testing the example so let's put https://www.myself.com/pp.
+* Set the "Application Type" to "Client".
+* Choose a Callback URL" (e.g., "example://fitbit/auth").
+* Choose a "Default Access Type" (e.g., "Read-Only").
+* Check the "I have read and agree to the terms of service" box.
+* Click the "Register" button. You should now see the "**OAuth 2.0 Client ID**" and the "**Client Secret**" strings provided by Fitbit.
+
+#### App authentication 
+
+You are now ready to authorize your application.
+
+To do that, simply call the asynchronous method `FitbitConnector.authorize()`, within your code, as: 
+
+```dart
+    FitbitCredentials? fitbitCredentials =
+        await FitbitConnector.authorize(
+            clientID: Strings.fitbitClientID,
+            clientSecret: Strings.fitbitClientSecret,
+            redirectUri: Strings.fitbitRedirectUri,
+            callbackUrlScheme: Strings.fitbitCallbackScheme
+        );
+```
+
+This will open a web view where user will be able to input his Fitbit credentials and login.
+After the login, the web view will close and the method will return a `FitbitCredentials?` instance that contains the credentials to be used to make requests to the Fitbit Web API via `fitbitter`. In particular, `fitbitCredentials.userID` contains the Fitbit user id of the user that just authorized `fitbitter`, `fitbitCredentials.fitbitAccessToken` contains the Fitbit access token, and `fitbitCredentials.fitbitRefreshToken` contains the Fitbit refresh token.
+
+::: warning 
+Since version 2.0.0, `fitbitter` no longer stores the credentials automatically. As such, you, as a developer, must manage such crendentials according to your strategy. 
+:::
+
+#### Fetch step count data
+
+With your app authorized, you are now ready to fetch data from Fitbit. In this example, we will fetch yesterday's step count.
+
+Using Fitbitter, this is very easy. First instanciate a `FitbitActivityTimeseriesDataManager` of `type: 'steps'`:
+
+```dart
+    FitbitActivityTimeseriesDataManager
+        fitbitActivityTimeseriesDataManager =
+        FitbitActivityTimeseriesDataManager(
+            clientID: '<OAuth 2.0 Client ID>',
+            clientSecret: '<Client Secret>',
+            type: 'steps', 
+        );
+```
+
+Then fetch the desired data using the `fetch` method of `FitbitActivityTimeseriesDataManager` with the proper `FitbitActivityTimeseriesAPIURL`:
+
+```dart 
+final stepsData = await fitbitActivityTimeseriesDataManager.fetch(
+    FitbitActivityTimeseriesAPIURL.dayWithResource(
+        date: DateTime.now().subtract(Duration(days: 1)),
+        userID: fitbitAccount.id,
+        resource: fitbitActivityTimeseriesDataManager.type,
+        fitbitCredentials: fitbitCredentials!,
+        )
+    ) as List<FitbitActivityTimeseriesData>;
+```
+
+That's it! 
+
+::: tip
+For more information on Fitbitter functionalities, check out the [Guides](https://gcappon.github.io/fitbitter/guides/) and the Fitbitter [Reference API](https://pub.dev/documentation/fitbitter/latest/)
+:::
+
+## Documentation & Guides
+
+For more docs and guides please refer to: [https://gcappon.github.io/fitbitter/](https://gcappon.github.io/fitbitter/).
+
 ## Support
 
-If you like my work, feel free to support me with a coffee.
+If you like my work, feel free to support me with a coffee. Thanks!
 
 [!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/gcappon)
diff --git a/example/lib/AndroidManifest.xml b/example/lib/AndroidManifest.xml
diff --git a/example/pubspec.lock b/example/pubspec.lock
@@ -70,7 +70,7 @@ packages:
       path: ".."
       relative: true
     source: path
-    version: "2.0.0"
+    version: "2.0.1"
   flutter:
     dependency: "direct main"
     description: flutter

diff --git a/lib/fitbitter.dart b/lib/fitbitter.dart
@@ -36,7 +36,7 @@ export 'package:fitbitter/src/managers/fitbitActivityTimeseriesDataManager.dart'
 export 'package:fitbitter/src/managers/fitbitBreathingRateDataManager.dart';
 export 'package:fitbitter/src/managers/fitbitCardioScoreDataManager.dart';
 export 'package:fitbitter/src/managers/fitbitDeviceDataManager.dart';
-export 'package:fitbitter/src/managers/fitbitHeartDataManager.dart';
+export 'package:fitbitter/src/managers/fitbitHeartRateDataManager.dart';
 export 'package:fitbitter/src/managers/fitbitHeartRateIntradayDataManager.dart';
 export 'package:fitbitter/src/managers/fitbitHeartRateVariabilityDataManager.dart';
 export 'package:fitbitter/src/managers/fitbitSleepDataManager.dart';

diff --git a/lib/src/data/fitbitCardioScoreData.dart b/lib/src/data/fitbitCardioScoreData.dart
@@ -14,15 +14,11 @@ class FitbitCardioScoreData implements FitbitData {
   /// The value of the data.
   double? value;
 
-  // The type of skin temeperature log created.
-  String? logType;
-
   /// Default [FitbitCardioScoreData] constructor.
   FitbitCardioScoreData({
     this.userID,
     this.dateOfMonitoring,
     this.value,
-    this.logType,
   });
 
   /// Generates a [FitbitCardioScoreData] obtained from a json.
@@ -31,7 +27,6 @@ class FitbitCardioScoreData implements FitbitData {
       userID: json['userID'],
       dateOfMonitoring: Formats.onlyDayDateFormatTicks.parse(json['dateTime']),
       value: json['value']['vo2Max'],
-      logType: json['logType'],
     );
   } // fromJson
 
@@ -43,7 +38,6 @@ class FitbitCardioScoreData implements FitbitData {
       'value': <String, dynamic>{
         'vo2Max': value,
       },
-      'logType': logType,
     };
   } // toJson
 
@@ -53,7 +47,6 @@ class FitbitCardioScoreData implements FitbitData {
           ..write('userID: $userID, ')
           ..write('dateOfMonitoring: $dateOfMonitoring, ')
           ..write('value: $value, ')
-          ..write('logType: $logType')
           ..write(')'))
         .toString();
   } // toString

diff --git a/lib/src/fitbitConnector.dart b/lib/src/fitbitConnector.dart
@@ -81,7 +81,6 @@ class FitbitConnector {
     final fitbitUrl = FitbitAuthAPIURL.refreshToken(
         clientID: clientID,
         clientSecret: clientSecret,
-        fitbitRefreshToken: fitbitCredentials.fitbitRefreshToken,
         fitbitCredentials: fitbitCredentials);
 
     // Post refresh query to Fitbit API

diff --git a/lib/src/managers/fitbitCardioScoreDataManager.dart b/lib/src/managers/fitbitCardioScoreDataManager.dart
@@ -47,7 +47,6 @@ class FitbitCardioScoreDataManager extends FitbitDataManager {
         dateOfMonitoring:
             Formats.onlyDayDateFormatTicks.parse(record['dateTime']),
         value: record['value']['vo2Max'].toDouble(),
-        logType: record['logType'],
       ));
     } // for entry
 

diff --git a/lib/src/managers/fitbitHeartDataManager.dart → .../managers/fitbitHeartRateDataManager.dart b/lib/src/managers/fitbitHeartDataManager.dart → .../managers/fitbitHeartRateDataManager.dart
diff --git a/lib/src/urls/fitbitAccountAPIURL.dart b/lib/src/urls/fitbitAccountAPIURL.dart
@@ -10,10 +10,14 @@ class FitbitAccountAPIURL extends FitbitAPIURL {
   /// Default [FitbitAccountAPIURL] constructor.
   FitbitAccountAPIURL(
       {required FitbitCredentials? fitbitCredentials, required String url})
-      : super(url: url, fitbitCredentials: fitbitCredentials) {
-    this.url = '${_getBaseURL()}.json';
-    this.fitbitCredentials = fitbitCredentials;
-  }
+      : super(url: url, fitbitCredentials: fitbitCredentials);
+
+  /// Return a [FitbitAccountAPIURL] from the given [fitbitCredentials].
+  factory FitbitAccountAPIURL.withCredentials(
+      {required FitbitCredentials fitbitCredentials}) {
+    final url = '${_getBaseURL()}.json';
+    return FitbitAccountAPIURL(fitbitCredentials: fitbitCredentials, url: url);
+  } // FitbitAccountAPIURL.withCredentials
 
   /// A private method that generates the base url of a [FitbitAccountAPIURL].
   static String _getBaseURL() {

diff --git a/lib/src/urls/fitbitAuthAPIURL.dart b/lib/src/urls/fitbitAuthAPIURL.dart
@@ -26,11 +26,11 @@ class FitbitAuthAPIURL extends FitbitAPIURL {
 
   /// Factory constructor that generates a [FitbitAuthAPIURL] to be used
   /// to refresh the access token.
-  factory FitbitAuthAPIURL.refreshToken(
-      {required FitbitCredentials fitbitCredentials,
-      required String clientID,
-      required String clientSecret,
-      required String fitbitRefreshToken}) {
+  factory FitbitAuthAPIURL.refreshToken({
+    required FitbitCredentials fitbitCredentials,
+    required String clientID,
+    required String clientSecret,
+  }) {
     // Generate the authorization header
     Codec<String, String> stringToBase64 = utf8.fuse(base64);
     final String authorizationHeader =
@@ -40,7 +40,7 @@ class FitbitAuthAPIURL extends FitbitAPIURL {
       url: '${_getBaseURL()}/token',
       fitbitCredentials: fitbitCredentials,
       data:
-          'client_id=$clientID&grant_type=refresh_token&refresh_token=$fitbitRefreshToken',
+          'client_id=$clientID&grant_type=refresh_token&refresh_token=${fitbitCredentials.fitbitRefreshToken}',
       authorizationHeader: 'Basic $authorizationHeader',
     );
   } // FitbitAuthAPIURL.refreshToken

diff --git a/lib/src/urls/fitbitDeviceAPIURL.dart b/lib/src/urls/fitbitDeviceAPIURL.dart
@@ -11,10 +11,14 @@ class FitbitDeviceAPIURL extends FitbitAPIURL {
   /// Default [FitbitDeviceAPIURL] constructor.
   FitbitDeviceAPIURL(
       {required FitbitCredentials? fitbitCredentials, required String url})
-      : super(url: url, fitbitCredentials: fitbitCredentials) {
-    this.url = '${_getBaseURL(fitbitCredentials!.userID)}.json';
-    this.fitbitCredentials = fitbitCredentials;
-  }
+      : super(url: url, fitbitCredentials: fitbitCredentials);
+
+  /// Return a [FitbitDeviceAPIURL] from the given [fitbitCredentials].
+  factory FitbitDeviceAPIURL.withCredentials(
+      {required FitbitCredentials fitbitCredentials}) {
+    final url = '${_getBaseURL(fitbitCredentials.userID)}.json';
+    return FitbitDeviceAPIURL(fitbitCredentials: fitbitCredentials, url: url);
+  } // FitbitDeviceAPIURL.withCredentials
 
   /// A private method that generates the base url of a [FitbitDeviceAPIURL].
   static String _getBaseURL(String? userID) {