FreemiumLibary

This library hasn't been updated for a while and shouldn't be used as such. Feel free to fork it and update it :)

The Android Freemium Library is a library that aims to help you put up a freemium model within your android application

What is a Freemium Business Model?

What I mean by Freemium Business Model is to propose users to use features from your apps for free, but will have to pay to use advanced features. They can also be shown ads when they are not premium - it's up to you.

How does this library helps?

This library implements and simplifies multiple functionalities that would be useful to you. It implements the in-app billing v3 used to charge user via the Google Play Store. It also implements the AdMob library that can be used to show ads to the user when he is not premium.

Prepare your application

First of all, you will need to create your application's project in the Play Store developer console, and create a "managed" in-app product (See Yourapp > In app products > Add new product). You will also need to note the License key of your application which is listed in the "Services & APIs" in the Developer Console.

You might also want to note your application's ad-unit key (Monetize > YourApp > Ad Unit ID)

You will also need to import the library to your application. In Eclipse, just import the project as an Android Library project.

If you are using Android Studio and gradle, the easiest way to add the FreemiumLibrary to your project is to add the following dependency to your build.gradle:

dependencies {
    compile 'com.magicmicky.freemiumlibrary:library:+'
}

Your App's Manifest

You also need to tweak a little your App's AndroidManifest.xml to add the library's permissions and activity. At the top level of your manifest, simply add

	<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
	<uses-permission android:name="android.permission.INTERNET"/>
	<uses-permission android:name="com.android.vending.BILLING" />

How to use the library?

To use the library you need to create an instance of a PremiumManager. It's advised to do so in the onResume() of your application, after setting up the content view of your activity.

	public PremiumManager(Activity activity, String premiumPackageId,String appPublicKey, String adId, Set<String> testDevices) {

The PremiumManager constructor will take a few arguments:

activity: The Activity currently running.
premiumPackageId: the premium package id of your Google Play upgrade package.
appPublicKey: Your app's licence Public Key that you can find on the Google Play store (in Services and API).
adId: Your AdMob key, so that it can show ads to the user.
testDevices: And a Set of test devices for AdMob.

To catch the return intent of the in-app payment, you will also need to implement the onActivityResult of your application and call the handleResult of your PremiumManager.

    @Override
    protected void onActivityResult(int requestCode, int resultCode, Intent intent) {
        if(!(mPremiumManager != null && mPremiumManager.handleResult(requestCode, resultCode, intent))) {
            Log.v(TAG, "Activity result not handled by PremiumManager");
            //Handle your own results...
        }
    }

Finally, you'll have to clean the PremiumManager in your activity's onDestroy call.

	protected void onDestroy() {
		super.onDestroy();
        if(mPremiumManager != null)
            mPremiumManager.clean();
	}

Once your premium manager and your activity are set up, you will be able to select the features you want to use.

Showing Ads when the user is not premium

To show ads for a non-premium user, you just need to set it up via the PremiumManager's doAdsForNonPremium method.

	public void doAdsForNonPremium(int adsViewGroupRes, boolean upgradeLinkOnFailure, Integer adsReplacementLayoutRes) throws PremiumModeException

The method doAdsForNonPremium will take as arguments:

adsViewGroupRes: The ViewGroup that should contain the ad. Be sure that the ad will fit in this viewgroup and check the LogCat if you don't see it. It should be something like R.id.my_container
upgradeLinkOnFailure: Whether or not you want an upgrade link when the ads can not be selected (i.e.: the user has no internet, or is using AdBlock)
adsReplacementLayoutRes: And finally, if the previous argument was set to "true" the replacement layout that should be inflated. It should be something like R.layout.replacement_layout.

The ad generated by AdMob is an AdSize.BANNER. This means that your adsViewGroupRes must measure at least 320x50 dp so that the ad can fit its container.

This method will throw some exception when the adsViewGroupRes isn't found or the adsReplacementLayoutRes doesn't exists. Note that a default replacement layout can be found in this project: R.layout.ads_replacement_default

Showing an upgrade button in your layout (i.e. in the drawer)

To show an upgrade button on your application, you just need to call the method doUpgradeButtonForNonPremium.

	public void doUpgradeButtonForNonPremium(int upgradeButtonViewGroupRes, int upgradeButtonLayoutReference) throws PremiumModeException

This method takes the following arguments

drawerButtonViewGroupRes: The ViewGroup that will contain the premium button. Should be something like R.id.container
drawerButtonLayoutReference: The layout to inflate in this viewgroup container. Should be something like R.layout.upgrade_button

It throws Exception when the drawerButtonLayoutReference doesn't exists or when the drawerButtonViewGroupRes isn't found. Note that a default layout can be found in this project for the upgrade buttons: R.layout.upgrade_to_premium_default

Showing an upgrade button in the Menu

You can also show an upgrade button in the menu. It will be available on pre and post honeycomb menu style. You just need to call doPremiumButtonInMenu in your Activity's onPrepareOptionsMenu

    @Override
    public boolean onPrepareOptionsMenu(Menu menu) {
        if(this.mPremiumManager!=null)
            this.mPremiumManager.doMenuButtonForNonPremium(menu, getString(R.string.action_premium));
        return super.onPrepareOptionsMenu(menu);
    }

This method will require the following arguments:

menu: The Menu where the new item should be created
menuButtonText: The String you want to show for the user to upgrade. (be sure to check the String's length!)

More advanced use.

You also have access to other methods that could be useful in other cases.

public boolean isPremium() will tell you if the user is premium or not. Thanks to it, you will be able to select features you want to activate only for premium users.

public static boolean getPremiumFromPrefs(Context c) will let you get the premium information for the preferences. It could be useful to use it in a widget or somewhere you don't want to instance a PremiumManager.

public boolean isInAppBillingSupported() will tell you whether or not the user's device support InAppBilling.

Feel free to check the javadoc if you require more information.

Featured projects.

The library is currently used in my HabitRPG application. You can find it on the Google Play Store

Developped by

Mickael Goubin - @MagicMicky

License

Copyright 2014 Mickael Goubin

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.

MagicMicky/FreemiumLibrary