From 7e0f2c43b682ac5928d8fbdd216307a8b09ae4de Mon Sep 17 00:00:00 2001 From: Youssef Ahmed Date: Sun, 12 Feb 2023 15:47:43 -0500 Subject: [PATCH] Updated README.md to include a Getting Started Section --- README.md | 291 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 192 insertions(+), 99 deletions(-) diff --git a/README.md b/README.md index f4d1f8c..ff7951b 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@

-

A free, open source, third party Android library to notify the update information about the installed android apps on an android device. The library has been built with the Kotlin language. Check out the wiki link. To support, Buy Me A Coffee

+

A free, open source, third party Android library to notify the update information about the installed android apps on an android device. The library has been built with the Kotlin language. Check out the wiki link. To support, Buy Me A Coffee

@@ -18,94 +18,174 @@

-## Description +## Description + AndroidAppUpdater is a free, open source, third party Android library for notifing update information to android apps installed on an android device. By its help, an old application is notified about update information from the Google Play Market. -`Library has built with Kotlin language on Android Studio IDE` and binaries have added to `jcenter()` `maven` repository. -You can check [jCenter() download statistics](https://bintray.com/hummatli/maven/android-app-updater#statistics) on this [link](https://bintray.com/hummatli/maven/android-app-updater#statistics) +`Library has built with Kotlin language on Android Studio IDE` and binaries have added to `jcenter()` `maven` repository. +You can check [jCenter() download statistics](https://bintray.com/hummatli/maven/android-app-updater#statistics) on this [link](https://bintray.com/hummatli/maven/android-app-updater#statistics) There is a list of [application using AndroidAppUpdater](https://github.com/hummatli/AndroidAppUpdater#applications-using-androidappupdater). It would be nice if see your app link there too. If you use this library and want to see your app in the start of the [list](https://github.com/hummatli/AndroidAppUpdater#applications-using-androidappupdater) please [inform me](mailto:settarxan@gmail.com) or send a pull request. -* [jCenter() download statistics](https://bintray.com/hummatli/maven/android-app-updater#statistics) -* [Application using AndroidAppUpdater](https://github.com/hummatli/AndroidAppUpdater#applications-using-androidappupdater) +- [jCenter() download statistics](https://bintray.com/hummatli/maven/android-app-updater#statistics) +- [Application using AndroidAppUpdater](https://github.com/hummatli/AndroidAppUpdater#applications-using-androidappupdater) - _**Don't forget to start the protect to support us**_ + _**Don't forget to start the protect to support us**_ ## Contributors -* Developer - Main functionality: -[Sattar Hummatli](https://github.com/hummatli) - [LinkedIn](https://www.linkedin.com/in/hummatli), settarxan@gmail.com, [Other libs](https://github.com/hummatli/AndroidAppUpdater#other-libraries-by-developer) -* Developer - Added new feature: -[andrewpros](https://github.com/andrewpros) , Thanks!, `New Feature: "Info Resolver"`. Now you can get information from your own formatted service -* Translator `Portuguese`: [azzarr](https://github.com/azzarr) , Thanks! -* Translator `Hindi`: [dalwadi2](https://github.com/dalwadi2), Thanks! -* Translator `German`: [Ndam Njoya](https://www.facebook.com/ndam.njoya), Thanks! -* Translator `French`: [Zeldarck](https://github.com/Zeldarck), Thanks!, Has changed sample apps to support `French`. -* Translator `Greek`: [Nikos Linakis](https://github.com/hastoukopsaro), Thanks!. + +- Developer - Main functionality: + [Sattar Hummatli](https://github.com/hummatli) - [LinkedIn](https://www.linkedin.com/in/hummatli), settarxan@gmail.com, [Other libs](https://github.com/hummatli/AndroidAppUpdater#other-libraries-by-developer) +- Developer - Added new feature: + [andrewpros](https://github.com/andrewpros) , Thanks!, `New Feature: "Info Resolver"`. Now you can get information from your own formatted service +- Translator `Portuguese`: [azzarr](https://github.com/azzarr) , Thanks! +- Translator `Hindi`: [dalwadi2](https://github.com/dalwadi2), Thanks! +- Translator `German`: [Ndam Njoya](https://www.facebook.com/ndam.njoya), Thanks! +- Translator `French`: [Zeldarck](https://github.com/Zeldarck), Thanks!, Has changed sample apps to support `French`. +- Translator `Greek`: [Nikos Linakis](https://github.com/hastoukopsaro), Thanks!. ## Contents -* [Description](https://github.com/hummatli/AndroidAppUpdater#description) -* [Service structure](https://github.com/hummatli/AndroidAppUpdater#service-structure) -* [Library structure](https://github.com/hummatli/AndroidAppUpdater#library-structure) -* [Installation manual](https://github.com/hummatli/AndroidAppUpdater#installation-manual) -* [Help - Issues](https://github.com/hummatli/AndroidAppUpdater#help---issues) -* [Releases - Upgrade documentation](https://github.com/hummatli/AndroidAppUpdater#releases---upgrade-documentation) -* [To contribute](https://github.com/hummatli/AndroidAppUpdater#to-contribute) -* [Contributors](https://github.com/hummatli/AndroidAppUpdater#contributors) -* [Localization](https://github.com/hummatli/AndroidAppUpdater#localization) -* [Applications using AndroidAppUpdater](https://github.com/hummatli/AndroidAppUpdater#applications-using-androidappupdater) -* [Other libraries by developer](https://github.com/hummatli/AndroidAppUpdater#other-libraries-by-developer) + +- [Description](https://github.com/hummatli/AndroidAppUpdater#description) +- [Service structure](https://github.com/hummatli/AndroidAppUpdater#service-structure) +- [Library structure](https://github.com/hummatli/AndroidAppUpdater#library-structure) +- [Installation manual](https://github.com/hummatli/AndroidAppUpdater#installation-manual) +- [Help - Issues](https://github.com/hummatli/AndroidAppUpdater#help---issues) +- [Releases - Upgrade documentation](https://github.com/hummatli/AndroidAppUpdater#releases---upgrade-documentation) +- [To contribute](https://github.com/hummatli/AndroidAppUpdater#to-contribute) +- [Contributors](https://github.com/hummatli/AndroidAppUpdater#contributors) +- [Localization](https://github.com/hummatli/AndroidAppUpdater#localization) +- [Applications using AndroidAppUpdater](https://github.com/hummatli/AndroidAppUpdater#applications-using-androidappupdater) +- [Other libraries by developer](https://github.com/hummatli/AndroidAppUpdater#other-libraries-by-developer) + +## Getting Started + +Here are the steps to get started with AndroidAppUpdater: + +**Step 1: Add the Library to Your Project** + +Add the following lines to your project's build.gradle file: + +```gradle +repositories { +maven { url 'https://dl.bintray.com/hummatli/maven/' } +} + +dependencies { +implementation 'com.mobapphome.androidappupdater:androidappupdater:1.3.3' +} +``` + +**Step 2: Implement the Update Info Service** + +Implement a service that provides information about the update status of your application. The service should respond with a JSON object that contains the following fields: + +- `is_run_mode`: Specifies if the update information should be used by the library. +- `name`: The name of the app. +- `uri_current`: The current package path of the app. +- `version_code_current`: The current version code available. +- `version_code_min`: The minimum version code that is required to use the app. +- `update_info`: Information about the update. +- `update_date`: The date of the update. + +Here's an example JSON object: + +```json +{ + "is_run_mode": "true", + "name": "AndroidAppUpdater Sample", + "uri_current": "com.mobapphome.mahandroidupdater.sample", + "version_code_current": "2", + "version_code_min": "1", + "update_info": "On version 1.0 we added bla bla", + "update_date": "16/07/2016" +} +``` + +**Step 3: Initialize the Library** + +In your main activity, call the following line of code in the `onCreate()` method: + +```kotlin +AAUpdaterController.init(this) +``` + +**Step 4: Show the Update Dialog** + +There are two types of update dialogs: `AAUpdaterDlg` and `AAUpdaterRestricterDlg`. The `AAUpdaterDlg` dialog allows the user to update or install the newer version of the app later, while the `AAUpdaterRestricterDlg` dialog urges the user to update or install the newer version of the app and doesn't allow the user to use the older version. + +You can show the `AAUpdaterDlg` dialog with the following code: + +```kotlin +AAUpdaterController.testUpdaterDlg(this) +``` + +And you can show the `AAUpdaterRestricterDlg` dialog with the following code: + +```kotlin +AAUpdaterController.testRestricterDlg(this) +``` ## Demo App + Download the demo app from this link - Demo App. You can easly test the lib's functionality. ## Service structure -To provide update information to your app you need to implement service responding json data about application current state. Structure of the json data is as below. + +To provide update information to your app you need to implement service responding json data about application current state. Structure of the json data is as below. You can provide `http://` and `https://` services. Library works both of them. Json with sample data. [Link](https://github.com/MobAppHome/MAHServiceForMyApps/blob/master/public/mah_android_updater_dir/mah_android_updater_sample.json) to working sample - + ```json { - "is_run_mode":"true", - "name":"AndroidAppUpdater Sample", - "uri_current":"com.mobapphome.mahandroidupdater.sample", - "version_code_current":"2", - "version_code_min":"1", - "update_info":"On version 1.0 we added bla bla", - "update_date":"16/07/2016" + "is_run_mode": "true", + "name": "AndroidAppUpdater Sample", + "uri_current": "com.mobapphome.mahandroidupdater.sample", + "version_code_current": "2", + "version_code_min": "1", + "update_info": "On version 1.0 we added bla bla", + "update_date": "16/07/2016" } ``` -* `is_run_mode` - service mode: if it's false modul will not react to service and will not show dialogs -* `name` - name of the belonging app -* `uri_current` - current package path -* `version_code_current` - current version code avilable -* `version_code_min` - Minimum version code, which does not work normal and had to force to update -* `update_info` - Update information -* `update_date` - Update date -If one of the variables would not be on json, then modul will not repond to service and act, Try to implement all data. +- `is_run_mode` - service mode: if it's false modul will not react to service and will not show dialogs +- `name` - name of the belonging app +- `uri_current` - current package path +- `version_code_current` - current version code avilable +- `version_code_min` - Minimum version code, which does not work normal and had to force to update +- `update_info` - Update information +- `update_date` - Update date + +If one of the variables would not be on json, then modul will not repond to service and act, Try to implement all data. You can check you json validity with this [jsonlint.com](http://jsonlint.com/) There is interface called `IUpdateInfoResolver` by the help of it you can fetch your update information form own structed service. For example `JSON API`, `XML`,`Raw text` and so on. For this reason there is special `init()` method accepting this variable. This feature has added by @andrewpros. - + ## Library structure + `You can call with the same way in Kotlin and Java. Library contains samples both in Kotlin and Java` Library components: -* `AAUpdaterDlg`- In this situation dialog show to user to update or install newer version and lets to postpone the action to later time and use application -* `AAUpdaterRestricterDlg` - In this situation dialog urges user to update or install newer version and dont alow use older version - + +- `AAUpdaterDlg`- In this situation dialog show to user to update or install newer version and lets to postpone the action to later time and use application +- `AAUpdaterRestricterDlg` - In this situation dialog urges user to update or install newer version and dont alow use older version + The porpose of lib to show automatically these dialogs on application start if there are any need for it. **-** `AAUpdaterDlg` opens on following situation. -* Or `uri_current` value is different from app's installed package url -* Or `version_code_current` value is greater than app's installed version on device + +- Or `uri_current` value is different from app's installed package url +- Or `version_code_current` value is greater than app's installed version on device **-** `AAUpdaterRestricterDlg` opens on all situation `AAUpdaterDlg` opens and following situation. -* `version_code_min` value is greater than app's installed version on device -But when you develop your apps UI and want to show these dialogs there are test modes also and you can open dialogs by calling methods relatively -* `AAUpdaterController.testUpdaterDlg(activity)` - `AAUpdaterDlg` -* `AAUpdaterController.testRestricterDlg(activity)` - `AAUpdaterRestricterDlg` +- `version_code_min` value is greater than app's installed version on device + +But when you develop your apps UI and want to show these dialogs there are test modes also and you can open dialogs by calling methods relatively + +- `AAUpdaterController.testUpdaterDlg(activity)` - `AAUpdaterDlg` +- `AAUpdaterController.testRestricterDlg(activity)` - `AAUpdaterRestricterDlg` ## Installation manual + The lib has compiled with the gradle 4.6. **1)** To import library to you project add following lines to project's `build.gradle` file. @@ -119,7 +199,7 @@ repositories { dependencies { //The android-app-updater libary implementation 'com.mobapphome.library:android-app-updater:1.3.3' - + //These dependencies have been used in this lib so you need to include them acording to gradle 3.0 and upper implementation 'com.google.code.gson:gson:2.8.2' implementation 'org.jsoup:jsoup:1.10.2' @@ -127,17 +207,20 @@ dependencies { ``` **2)** On the start of your application call `AAUpdaterController.init()` method to initialize modul. For example: MainActivity's `onCreate()` method or in splash activity. Check http url is correct and points to your service on the web. -Code: +Code: + ```java kotlin AAUpdaterController.init(activity,"http://highsoft.az/android-app-updater-sample.php") ``` -**3)** When you quit app, you have to call `AAUpdaterController.end()` method to finalize modul. For example: MainActivity's `onDestroy()` method. +**3)** When you quit app, you have to call `AAUpdaterController.end()` method to finalize modul. For example: MainActivity's `onDestroy()` method. + ```java kotlin - AAUpdaterController.end() + AAUpdaterController.end() ``` **4)** To customize `AndroidAppUpdater` dialog UI and overide colors set these values on your main projects `color.xml` file + ```xml #FFFFFFFF #FF3F51B5 @@ -147,15 +230,16 @@ Code: #ff3F51B5 #ffffffff - #ffFF4081 + #ffFF4081 ``` -**5)** `Localization:` Following languages is supporting by the lib - [Supported Languages](https://github.com/hummatli/AndroidAppUpdater#localization). To set localization to app use your own method or if it is static and don't change in program session you can just simply add `LocaleUpdater.updateLocale(this, "your_lang");` in the start of your app. For examlpe `LocaleUpdater.updateLocale(this, "ru");` +**5)** `Localization:` Following languages is supporting by the lib - [Supported Languages](https://github.com/hummatli/AndroidAppUpdater#localization). To set localization to app use your own method or if it is static and don't change in program session you can just simply add `LocaleUpdater.updateLocale(this, "your_lang");` in the start of your app. For examlpe `LocaleUpdater.updateLocale(this, "ru");` **6)** To customize `AndroidAppUpdater` UI texts and overide them add these lines to main projects `string.xml` and set them values. To help translators there prefixes on the name of strings -* < command verb (actions)> - These are commands verbs. Meaninaction on UI , dialogs -* < noun > - these are nouns not action (verb) + +- < command verb (actions)> - These are commands verbs. Meaninaction on UI , dialogs +- < noun > - these are nouns not action (verb) ```xml Update information @@ -182,80 +266,89 @@ To help translators there prefixes on the name of strings **7)** To customize `Info button` on the `right - upper` corner of dialogs. You can do it with help of `AAUpdaterController.init()` method. It has three version. `init()`This method well documented and you can see it when developing your app. You can do followings with `Info button`: -* Change visibility -* Set your own name or url to open when click on info button -* Open popup menu or act as button when click on info button +- Change visibility +- Set your own name or url to open when click on info button +- Open popup menu or act as button when click on info button **8)** As modul takes information from web servcie you need add `INTERNET` permission to main project. + ```xml ``` ## Proguard configuration + AndroidAppUpdater uses Gson and Jsoup libs. There for if you want to create your project with proguard you need to add proguard configuration to your proguard file. Look at [Progurda File](https://github.com/hummatli/AndroidAppUpdater/blob/master/proguard-rules-android-app-updater.pro). ## Help - Issues + If you have any problem with setting and using library or want to ask question, please let me know. Create [issue](https://github.com/hummatli/AndroidAppUpdater/issues) or write to settarxan@gmail.com. I will help. ## To contribute -I am open to hear offers and opinions from you -* Fork it -* Create your feature branch (git checkout -b my-new-feature) -* Commit your changes (git commit -am 'Added some feature') -* Push to the branch (git push origin my-new-feature) -* Create new Pull Request -* Star it +I am open to hear offers and opinions from you + +- Fork it +- Create your feature branch (git checkout -b my-new-feature) +- Commit your changes (git commit -am 'Added some feature') +- Push to the branch (git push origin my-new-feature) +- Create new Pull Request +- Star it ## Localization -Library now supports following languages -* Azerbaijan -* English -* German -* Greek -* Hindi -* Portuguese -* Russia -* Turkey -* [Add your language](https://github.com/hummatli/AndroidAppUpdater/blob/master/README.md#to-contribute-for-localization) + +Library now supports following languages + +- Azerbaijan +- English +- German +- Greek +- Hindi +- Portuguese +- Russia +- Turkey +- [Add your language](https://github.com/hummatli/AndroidAppUpdater/blob/master/README.md#to-contribute-for-localization) ### To contribute for localization + **To help translator in context I have added prefixes to the start of the string names. -Be carefull when translating. Prefixes are following:** -_* < command verb (actions)> - These are commands verbs. Meaninaction on UI , dialogs_ -_* < noun > - these are nouns not action (verb)_ +Be carefull when translating. Prefixes are following:** +_\* < command verb (actions)> - These are commands verbs. Meaninaction on UI , dialogs_ +_\* < noun > - these are nouns not action (verb)_ -We need help to add new language localization support for libarary. If you have any hope to help us we were very happy and you can check following GitHub Issues URL to contribute. To contribute get GitHub Issues URL to contribute. To contribute get | [Indian Railway PNRStatus IRCTC](https://play.google.com/store/apps/details?id=com.emilartin.travel.indianrailwaypnrstatusirctc) - | [Миллионер - на Pусском](https://play.google.com/store/apps/details?id=iqra.viktorina.intellektualnoy.iq.millionaire.russian.millioner.russkiy) | | [Milyoner - Türkçe](https://play.google.com/store/apps/details?id=oyun.bilgi.entellektuel.iq.millionaire.turkish.milyoner.turkce) - | [Millionaire - in English](https://play.google.com/store/apps/details?id=game.quiz.intellectual.iq.millionaire.english) | | [Məzənnə](https://play.google.com/store/apps/details?id=com.mobapphome.currency) - | [AppCrossPromoter - Sample](https://play.google.com/store/apps/details?id=com.mobapphome.mahads.sample) | | [AndroidAppUpdater - Sample](https://play.google.com/store/apps/details?id=androidappupdater.sample) - | [SimpleEncryptorLib - Sample](https://play.google.com/store/apps/details?id=com.mobapphome.mahencryptorlib) | | [Ləzzət](https://play.google.com/store/apps/details?id=com.mobapphome.lezzet) - | [Milyonçu](https://play.google.com/store/apps/details?id=oyun.test.sualcavab.iq.millionaire.azerbaijani.milyoncu.azerbaycanca) | | [Millionär - Deutsche](https://play.google.com/store/apps/details?id=spiel.quiz.intellektuell.iq.millionaire.german.millionar.deutsche) +Please [ping](mailto:settarxan@gmail.com) me or send a pull request if you would like to see your app in the start of the list. +| Icon | Application | Icon | Application | +| ------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| [Your app] | [ping](mailto:settarxan@gmail.com) me or send a pull request | | [Indian Railway PNRStatus IRCTC](https://play.google.com/store/apps/details?id=com.emilartin.travel.indianrailwaypnrstatusirctc) | +| | [Миллионер - на Pусском](https://play.google.com/store/apps/details?id=iqra.viktorina.intellektualnoy.iq.millionaire.russian.millioner.russkiy) | | [Milyoner - Türkçe](https://play.google.com/store/apps/details?id=oyun.bilgi.entellektuel.iq.millionaire.turkish.milyoner.turkce) | +| | [Millionaire - in English](https://play.google.com/store/apps/details?id=game.quiz.intellectual.iq.millionaire.english) | | [Məzənnə](https://play.google.com/store/apps/details?id=com.mobapphome.currency) | +| | [AppCrossPromoter - Sample](https://play.google.com/store/apps/details?id=com.mobapphome.mahads.sample) | | [AndroidAppUpdater - Sample](https://play.google.com/store/apps/details?id=androidappupdater.sample) | +| | [SimpleEncryptorLib - Sample](https://play.google.com/store/apps/details?id=com.mobapphome.mahencryptorlib) | | [Ləzzət](https://play.google.com/store/apps/details?id=com.mobapphome.lezzet) | +| | [Milyonçu](https://play.google.com/store/apps/details?id=oyun.test.sualcavab.iq.millionaire.azerbaijani.milyoncu.azerbaycanca) | | [Millionär - Deutsche](https://play.google.com/store/apps/details?id=spiel.quiz.intellektuell.iq.millionaire.german.millionar.deutsche) | ## Other libraries by developer -* [![AppCrossPromoter](https://img.shields.io/badge/GitHUB-AppCrossPromoter-green.svg)](https://github.com/hummatli/AppCrossPromoter) - Library for advertisement own apps through your other apps. -* [![SimpleEncryptorLib](https://img.shields.io/badge/GitHUB-SimpleEncryptorLib-green.svg)](https://github.com/hummatli/SimpleEncryptorLib) - Library for encryption and decryption strings on Android apps and PC Java applications. + +- [![AppCrossPromoter](https://img.shields.io/badge/GitHUB-AppCrossPromoter-green.svg)](https://github.com/hummatli/AppCrossPromoter) - Library for advertisement own apps through your other apps. +- [![SimpleEncryptorLib](https://img.shields.io/badge/GitHUB-SimpleEncryptorLib-green.svg)](https://github.com/hummatli/SimpleEncryptorLib) - Library for encryption and decryption strings on Android apps and PC Java applications. ## License -Copyright 2017 - Sattar Hummatli + +Copyright 2017 - Sattar Hummatli Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at - http://www.apache.org/licenses/LICENSE-2.0 +http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS,