diff --git a/CHANGELOG.md b/CHANGELOG.md index 38efe83..a576e05 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,12 @@ +## 1.2.1 + +- docs: Fix broken images in README.md + +## 1.2.0 + +- enhance: Simplify get functions +- docs: Update README.md + ## 1.1.0 - enhance: Early return if response payload is empty diff --git a/README.md b/README.md index 717cb3a..5482038 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,146 @@ # Dart Google Sheet Remote Config -This is a Dart package that allows you to use Google Sheets as a remote config for your Dart/Flutter app. It is inspired by @theapache64's [blog](https://theapache64.github.io/posts/google-sheet-as-remote-config-for-microcontrollers/). +[![pub package](https://img.shields.io/pub/v/dart_gsheet_remote_config.svg)](https://pub.dev/packages/dart_gsheet_remote_config) -## Why Google Sheets? +This is a package that allows you to use Google Sheets as a remote config for changing your Dart/Flutter app's behaviors, settings,.. without updating. It is inspired by @theapache64's [blog](https://theapache64.github.io/posts/google-sheet-as-remote-config-for-microcontrollers/). + +## How it works + +- This package uses [Query Visualization API](https://developers.google.com/chart/interactive/docs/querylanguage) and some tricks to get data from Google Sheet. + +## MUST READ before use + +- If you have some configs (API key, token,...) related to security, please **DO NOT** use this package, because it is **PUBLIC** and **NOT SECURE**. + +## Setup + +### Google Sheet + +- Create a Google Sheet document, make it **PUBLIC** (If not you will get 401, in the future I will find the way to inject auth token for private sheeet) and put an easy to remember document name. + +![image](https://github.com/dungngminh/dart_gsheet_remote_config/raw/main/art/image.png) + +- Add your data to sheet in format: + - First column will be keys + - Second column will be values + +![image_2](https://github.com/dungngminh/dart_gsheet_remote_config/raw/main/art/image_2.png) + +- **MUST READ**: Every values in sheet is marked as **String**. For **int**, **doube**, **bool**, we should convert it to **String**, use `TO_TEXT` fomular to convert value to **String** type: + +![image_3](https://github.com/dungngminh/dart_gsheet_remote_config/raw/main/art/image_3.png) + +- You can create more than 1 worksheet to manage your config better and it can be selected to get correct data. + +![image_4](https://github.com/dungngminh/dart_gsheet_remote_config/raw/main/art/image_4.png) + +### Dart + +```sh +dart pub add dart_gsheet_remote_config +``` + +### Flutter + +```sh +flutter pub add dart_gsheet_remote_config +``` ## How to use + +Create your `SheetRemoteConfig` instance. + +```dart +import 'package:dart_gsheet_remote_config/dart_gsheet_remote_config.dart'; + +final remoteConfig = SheetRemoteConfig(); +``` + +`SheetRemoteConfig` has a param `Client` from `http` package so you can pass your custom `Client` object when create `SheetRemoteConfig` instance. + +```dart +import 'package:dart_gsheet_remote_config/dart_gsheet_remote_config.dart'; +import 'package:http/http.dart' as http; + +final client = http.Client(); + +final remoteConfig = SheetRemoteConfig(client: client); +``` + +### Fetch remote config data + +`SheetRemoteConfig` provides `initilize` function and you must pass `id` and `sheetName` to initilize remote config: + +- Document `id` you can find it in your Google Sheet document Url. For example your Sheet url is `https://docs.google.com/spreadsheets/d/123456789`, `id` will be `123456789`. + +- `sheetName` is worksheet name, **nullable**, first worksheet will be used if `null` or passed value is not found. + +```dart +import 'package:dart_gsheet_remote_config/dart_gsheet_remote_config.dart'; + +final remoteConfig = SheetRemoteConfig(); + +await remoteConfig.initilize(id: '123456789'); // First worksheet will be used + +await remoteConfig.initilize(id: '123456789', sheetName: 'Sheet1'); // Use specific worksheet name +``` + +**MUST READ**: `id` mustn't be hardcode if you don't want others to use your remote config. You can use `id` as `.env` field or via `dart-define` and pass it to your app via environment variable. You can use some packages like [`flutter_dotenv`](https://pub.dev/packages/flutter_dotenv), [`envied`](https://pub.dev/packages/envied) to load `.env` file. + +### Get data from remote + +`SheetRemoteConfig` fetchs data in CSV format, data is returned in key-value format, you can `key` to get `value` via +get functions, currently `SheetRemoteConfig` supports `String`, `int`, `double`, `bool`. + +Example response: + +```csv +"key1","TRUE" +"key2","10" +"key3","value from key 3" +"key4,"1.0" +``` + +And get data: + +```dart +final valueKey1 = remoteConfig.getBool('key1'); +print(valueKey1); // true + +final valueKey2 = remoteConfig.getInt('key2'); +print(valueKey2); // 10 + +final valueKey3 = remoteConfig.getString('key3'); +print(valueKey3); // value from key 3 + +final valueKey4 = remoteConfig.getDouble('key4'); +print(valueKey4); // 1.0 +``` + +If provided `key` is not found or provided `T` is incorrect, get functions will return `null`. + +```dart +final valueKey5 = remoteConfig.getString('key5'); +print(valueKey5); // null +``` + +You can pass `defaultValue` when get functions returns `null`. + +```dart +final valueKey5 = remoteConfig.getString('key5', defaultValue: 'this is default value'); +print(valueKey5); // this is default value +``` + +## Get all data from remote + +`SheetRemoteConfig` provides `getAll` function to get all data from remote. + +```dart +final allData = remoteConfig.getAll(); +print(allData); // {key1: true, key2: 10, key3: value from key 3, key4: 1.0} + +``` + +## Happy coding + +That's all for now! Want a feature? Found a bug? Create an [issue](https://github.com/dungngminh/dart_gsheet_remote_config/issues/new)! diff --git a/art/image.png b/art/image.png new file mode 100644 index 0000000..158b888 Binary files /dev/null and b/art/image.png differ diff --git a/art/image_2.png b/art/image_2.png new file mode 100644 index 0000000..70c44f6 Binary files /dev/null and b/art/image_2.png differ diff --git a/art/image_3.png b/art/image_3.png new file mode 100644 index 0000000..fb90c12 Binary files /dev/null and b/art/image_3.png differ diff --git a/art/image_4.png b/art/image_4.png new file mode 100644 index 0000000..3d1e411 Binary files /dev/null and b/art/image_4.png differ diff --git a/pubspec.lock b/pubspec.lock index 2e2c22a..3d0162c 100644 --- a/pubspec.lock +++ b/pubspec.lock @@ -5,23 +5,23 @@ packages: dependency: transitive description: name: _fe_analyzer_shared - sha256: "16e298750b6d0af7ce8a3ba7c18c69c3785d11b15ec83f6dcd0ad2a0009b3cab" + sha256: "45cfa8471b89fb6643fe9bf51bd7931a76b8f5ec2d65de4fb176dba8d4f22c77" url: "https://pub.dev" source: hosted - version: "76.0.0" + version: "73.0.0" _macros: dependency: transitive description: dart source: sdk - version: "0.3.3" + version: "0.3.2" analyzer: dependency: transitive description: name: analyzer - sha256: "1f14db053a8c23e260789e9b0980fa27f2680dd640932cae5e1137cce0e46e1e" + sha256: "4959fec185fe70cce007c57e9ab6983101dbe593d2bf8bbfb4453aaec0cf470a" url: "https://pub.dev" source: hosted - version: "6.11.0" + version: "6.8.0" args: dependency: transitive description: @@ -194,10 +194,10 @@ packages: dependency: "direct dev" description: name: lints - sha256: "4a16b3f03741e1252fda5de3ce712666d010ba2122f8e912c94f9f7b90e1a4c3" + sha256: "976c774dd944a42e83e2467f4cc670daef7eed6295b10b36ae8c85bcbf828235" url: "https://pub.dev" source: hosted - version: "5.1.0" + version: "4.0.0" logging: dependency: transitive description: @@ -210,10 +210,10 @@ packages: dependency: transitive description: name: macros - sha256: "1d9e801cd66f7ea3663c45fc708450db1fa57f988142c64289142c9b7ee80656" + sha256: "0acaed5d6b7eab89f63350bccd82119e6c602df0f391260d0e32b5e23db79536" url: "https://pub.dev" source: hosted - version: "0.1.3-main.0" + version: "0.1.2-main.4" matcher: dependency: transitive description: diff --git a/pubspec.yaml b/pubspec.yaml index 2f925b4..5d44590 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,6 +1,7 @@ name: dart_gsheet_remote_config -description: Remote config for Dart/Flutter and use Google Sheets to do that -version: 1.1.0 +description: A package that allows you to use Google Sheets as a remote config for changing your Dart/Flutter app's behaviors, settings,.. without updating. +version: 1.2.1+1 +topics: [remote, config] repository: https://github.com/dungngminh/dart_gsheet_remote_config issue_tracker: https://github.com/dungngminh/dart_gsheet_remote_config/issues