MAHAds - MobAppHome advertisment library

Contributors

• Developer: Sattar Hummatli - LinkedIn, settarxan@gmail.com, Other libs
• Translator French: Fariz Aghayev
• Translator Portuguese: azzarr

Contents

• Description
• Service structure
• Library structure
• Installation manual
• Help - Issues
• Releases - Upgrade documentation
• To contribute
• Contributors
• Localization
• Applications using MAHAds
• Other libraries by developer

Description

Library for advertisement own apps through your other apps. By the help of this lib you can provide your apps list to users through your own other apps and let to install them. Library has build on IDE Android Studio and binaries have added to jcenter() maven repository.
You can check jCenter() download statistics on this link - https://bintray.com/hummatli/maven/mah-ads#statistics

There is a list of application using MAHAds. 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 please inform me or send a pull request.

Sample App in PlayStore

MAHAds - Sample app has published on Google PlayStore. You can easly test module functionality with downloading it.

Service structure

To provide your apps list you have to implement service provider. Structure of the service is as below. Your root folder has to contain imgs folder and two files program_version.json, program_list.json.

Now you can set canonical - imgs/avto_nishanlar2.png and noncanonical - https://highsoft.az/avto_nishanlar2.png link to image for example.

root->
    imgs			- "contains logos for your porgram on the list"
    program_version.json 	- "show the ads service version."
    program_list.json 		- "contains program list"

program_version.json service has to return json as below.

	{
	 "version":"13"
	}

program_list.json service has to return json as below. There is two application in this sample:

	{
	"programs":[ 
		{
		  "name":"Avto Nişanlar", 
		  "desc":"Bütün yol nişanları", 
		  "uri":"com.mobapphome.avtonishanlar",  
		  "img":"imgs/avto_nishanlar2.png", 
		  "release_date":"22/12/2016",
		  "update_date":"22/12/2016"
		 },
		 {
		   "name":"Məzənnə", 
		   "desc":"Valyuta çeviricisi və məzənnələr", 
		   "uri":"com.mobapphome.currency",  
		   "img":"https://highsoft.az/mezenne2.png", 
		   "release_date":"22/12/2016",
		   "update_date":"22/12/2016"
		 }
	]
	}

release_date and update_date can be missed. Data will read.
Library has testes with up to 1000 program items in program list. It works normally.
You can provide http:// and https:// services. Library works both of them.
You can check you json validity with this jsonlint.com

Library structure

Library has MAHAdsController.init() method. It initialize modul, downloads program list from service and cashes them.

Library contains from to Dialog component

• MAHAdsDlgExit- This dialog calls when app quits and offers user quit or stay in app. By the way it offers random two application from your list
• MAHAdsDlgPrograms - This dialog list your application from service and let you open nd install them

Installation manual

1) To import library to you project add following lines to project's build.gradle file. The last stable version is 2.0.4

	dependencies {
    		compile 'com.mobapphome.library:mah-ads:2.0.4'
	}

2) Call MAHAdsController.init() in your project's starting point. For example: MainActivity's onCreate() method or in splash activity. Check url to point your services root path. MAHAdsController.init() method has two variation with different arguments. Code:

	MAHAdsController.init(this,"http://highsoft.az/mahads/", "github_apps_prg_version.json", "github_apps_prg_list.json")

3) Call MAHAdsController.callExitDialog() when your app quits. It opens MAHAdsDlgExit dilog. MAHAdsController.callExitDialog() method has three variation with different arguments. By the help oh this arguments you can customize Info button on the upper right corner of dilog. Code:

	public void onBackPressed() {
		MAHAdsController.callExitDialog(activity);
	}

Note: To implement MAHAdsDlgExit Dialog's onYes(), onNo(), onExitWithoutExitDlg() , onEventHappened(String eventStr) your main activity has to implement MAHAdsExitListener. Otherwise it will through ClassCastExeption. "Your activity must implement MAHAdsExitListener"

	public class MainActivity extends AppCompatActivity implements MAHAdsExitListener{
	   @Override
    	   public void onYes() {}

    	   @Override
           public void onNo() {}

           @Override
           public void onExitWithoutExitDlg() {}

           @Override
           public void onEventHappened(String eventStr) {}
	}

4) To open MAHAdsDlgPrograms call MAHAdsController.callProgramsDialog(). In library sample it has added to menu. MAHAdsController.callProgramsDialog() method has three variation with different arguments. By the help oh this arguments you can customize Info button on the upper right corner of dilog. Code:

	MAHAdsController.callProgramsDialog(activity);

5) To customize MAHAds dialog UI and overide colors set these values on your main projects color.xml file

	<color name="mah_ads_window_background_color">#FFFFFFFF</color>
	<color name="mah_ads_title_bar_color">#FF3F51B5</color>
	<!--new--> <color name="mah_ads_title_bar_text_color">#ffffff</color> 
	<color name="mah_ads_colorAccent">#FFFF4081</color>

	<color name="mah_ads_all_and_btn_text_color">#FF3F51B5</color>
	<!--new--> <color name="mah_ads_no_image_color">#3F51B5</color>
	<!--new--> <color name="mah_ads_program_item_desc_text_color">#4a76e6</color> 
	<color name="mah_ads_question_txt_color">#FF3F51B5</color>
	<color name="mah_ads_yes_no_txt_color">#FFFF4081</color>

	<color name="mah_ads_btn_other_border_color">#848ed2</color>
	<color name="mah_ads_btn_background_color_pressed">#333F51B5</color>

	<color name="mah_ads_text_view_new_background_color">#FF0000</color>
	<color name="mah_ads_text_view_new_text_color">#FFFFFFFF</color>
	<color name="mah_ads_no_img_color">#333F51B5</color>			

7) Localization: Following languages is supporting by the lib - Supported Languages. 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");

8) To customize MAHAds UI texts and overide them add these lines to main projects string.xml and set them values

    <string name="mah_ads_close">Close</string>
    <string name="mah_ads_dlg_title">Recommended</string>
    <string name="mah_ads_text_google_play">Open in GooglePlay</string>
    <string name="mah_ads_info_version">Version</string>
    <string name="mah_ads_internet_update_error">Error, please check internet connection and try again.</string>
    <string name="mah_ads_open_program">Open</string>
    <string name="mah_ads_install_program">Install</string>
    <string name="mah_ads_refresh_btn">Retry</string>
    <string name="mah_ads_free_aps">Recommended applications</string>
    <string name="mah_ads_new_text">New</string>
    <string name="mah_ads_updated_text">Updated</string>

    <string name="mah_ads_dlg_exit_question">Do you want exit?</string>
    <string name="mah_ads_dlg_exit_positive_btn_txt">Exit</string>
    <string name="mah_ads_dlg_exit_negativ_btn_txt">Stay</string>
    
    <string name="mah_ads_dlg_exit_btn_more_txt_1">Applications</string>
    <string name="mah_ads_dlg_exit_btn_more_txt_2">Detailed</string>

    <string name="mah_ads_info_popup_text">MAHAds library</string>
    <!--new--> <string name="mah_ads_play_service_not_found">Install Google Play Services to install application</string>

Note You can even customize dialogs in your application. Copy layout/mah_ads_dialog_programs.xml, layout/mah_ads_dialog_exit.xmlfiles and put in your layot dir and customize them as you want. But keep view ids as they are. They will overide older ones from library.

8) As modul takes information from web servcie you need add INTERNET permission to main project.

	<uses-permission android:name="android.permission.INTERNET" />

Proguard configuration

MAHAds uses Jsoup lib. There for if you want to create your project with proguard you need to add following configuration to your proguard file.

##-----------------To show exceptions right --------------------------------------
-keep public class * extends java.lang.Exception

##---------------Begin: proguard configuration for Jsoup--------------------------------
-keep public class org.jsoup.** {
public *;
}
##---------------End: proguard configuration for Jsoup--------------------------------

##---------------Begin: proguard configuration for Bumptech/Glide--------------------------------
-keep public class * implements com.bumptech.glide.module.GlideModule
-keep public enum com.bumptech.glide.load.resource.bitmap.ImageHeaderParser$** {
  **[] $VALUES;
  public *;
}
#Following is needed for Glide on DexGuard only. Uncomment it when DexGuard
#-keepresourcexmlelements manifest/application/meta-data@value=GlideModule
##---------------End: proguard configuration for Bumptech/Glide--------------------------------

Help - Issues

If you have any problem with setting and using library or want to ask question, please let me know. Create issue or write to settarxan@gmail.com. I will help.

Releases - Upgrade documentation

See releases. Please,read release notes to migrate your app from old version to a newer.

To contribute

I am open to here 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

• English
• Azerbaijan
• Portuguese
• Russia
• Turkey
• French
• Add yours language

To contribute for localization

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 res/values/string.xml file and translate to newer language. Place it on res/values-"spacific_lang"/string.xml

Applications using MAHAds

Please feel free to contact me or submit a pull request to add your app in the start of the list.

Icon	Application	Icon	Application
[Your app]	ping me or send a pull request		Millionaire - in English
	Миллионер - на Pусском		Milyoner - Türkçe
	Milyonçu		Məzənnə
	MAHAds - Sample		DYP Qanunlar və Cərimələr
	Avto Nişanlar		Ləzzət

Other libraries by developer

• - Android update checker library. Library for notifing update information to installed android apps on android device.
• - Library for encryption and decryption strings on Android apps and PC Java applications.

License

Copyright 2015 - 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

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.