Integration guide for Android

Process to start selling your own game merchandise from within game

Version: 3

Date: 16/07/2019

Process:


About

Monetizr Android SDK is a library, built upon Monetizr RESTful API to allow smoother integration with Monetizr.

Monetizr SDK is written using singleton pattern (or anti-pattern). The choice was obvious, it allows easier integration and does not require hardcore set-up.

For games developed on Unity ( Integration guide for Unity ) we offer a multi-platform plugin that supports both iOS and Android. However, if you have developed game on Android platform, please use the following instructions.

Monetizr Android SDK available at : https://github.com/themonetizr/monetizr-android-sdk


1.Integration

Prerequisites

Monetizr Android SDK minimal Android SDK version is 21 (Android Lollipo 5.0 starting)

To start using Monetizr SDK, you will need your own API access token and custom rewards, designed for your game by Monetizr team.

Access tokens are being given per request, contact: martins@themonetizr.com

For testing purposes you can use access token: 4D2E54389EB489966658DDD83E2D1

Monetizr SDK is published using jCenter. You can, of course download/clone repository and add it as a module dependency to your project.

Monetizr is providing a per-client based API key`s. We are using oAuth 2 authentication and simplifying that for our client SDKs. API is a public two-way, that does not expose any useful information, but still be aware of this limitation. API settings are being provided in-application.


1.1. First integration approach (preferred) - using gradle

Add Monetizr sdk as dependecy in your application build.gradle file

dependencies {
    implementation 'io.monetizr.monetizrsdk:MonetizrSDK:1.0.0'
}

or if you are using Maven:

<dependency>
    <groupId>io.monetizr.monetizrsdk</groupId>
    <artifactId>MonetizrSDK</artifactId>
    <version>1.0.0</version>
    <type>pom</type>
</dependency>

1.2. Second integration approach

Adding Monetizr SDK as a dependency:

  • Open your project in Android Studio
  • Download the library (using Git, or a zip archive to unzip)
  • Go to File > Import Module and import the library as a module
  • Right-click your app in project view and select “Open Module Settings”
  • Click the “Dependencies” tab and then the ‘+’ button
  • Select “Module Dependency”
  • Select “Library Project”
  • Modify the library if you want to

1.3. Third integration approach

Adding Monetizr SDK as a dependency in another way:

  • Open your project in Android Studio
  • Download the library (using Git, or a zip archive to unzip)
  • Create a folder “subProject” in your project
  • Copy and paste the library folder to your subProject folder
  • On the root of your project directory create/modify the settings.gradle file. It should contain something like the following:
  • gradle clean & build/close the project and reopen/re-import it.
  • Edit your project’s build.gradle to add this in the “dependencies” section:

2.Using sdk in your application

Your application needs to have some initial settings before calling SDK:


2.1. API key provided by Monetizr team

Adding the API key: must be called once, before invoking Monetizr Library for the first time in your application. For example, you can call this provided code-line in onCreate() method in your application before invoking Monetizr (you can, of course, call it wherever you want in your application, even just before every call to Monetizr library)

MonetizrSdk.apikey = "API key provided from Monetizr team"

Default API key is “4D2E54389EB489966658DDD83E2D1”, and it is provided with initial example rewards. No other necessary settings are needed to start working with Android SDK.


2.2. If you wish to see logging output, you can enable logging by:

MonetizrSdk.debuggable = true

2.3. Library defines two permissions, access to internet and necessity to check for internet connection (we are not supporting offline mode at this moment)

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

2.4. You will need to have your own reward tags, contact Monetizr team to acquire them

They are added for each API key, for example, for default api key (4D2E54389EB489966658DDD83E2D1) Monetizr provides following rewards tags:

  • Sample shirt
  • Sample pin
  • Sample gift card
  • sample-100-credits
  • sample-1000-credits

2.5. To invoke reward window, call Monetizr static method from within you application by providing available reward tag

One call will invoke one reward window. Whenever you are ready to show reward window inside your application, you can invoke Monetizr sdk to show reward window

MonetizrSdk.showProductForTag("Sample shirt")

MonetizrSdk.showProductForTag("Sample pin")

MonetizrSdk.showProductForTag("Sample gift card")

MonetizrSdk.showProductForTag("sample-100-credits")

MonetizrSdk.showProductForTag("sample-1000-credits")

2.6. Additional available public method, to make better in-game decisions

We are suggesting and not implying, on collecting some additional telemetric information about your game, so Monetizr would be able to suggest better decisions on how to improve monetization process.

Methods are calling API and safely storing provided bits of the data using queued HTTPS requests. If something will not work as expected, methods are not going to interfere with the host application and will not print out logging to console.

There are more methods included in SDK - those will be relevant in other scenarios

  • Store information about encounter (action) that was used to invoke reward. This will help to link emotional triggers with reward analysis, even if it is a simple reward for returning player. As this is not automatically, manual input is necessary from developer. We are strongly suggesting to call this method right before or right after invoking initial reward window.
Telemetrics.encounter("trigger_tag", "completionStatus", "triggerTag","levelName", "difficultyLevelName", "difficultyEstimation")

3. How to integrate SDK into your game

3.1. Applying behavioral incentives

For those new to the game, Octalysis is gamification framework that defines 8 core drives behind human motivation. The system was designed by Yu-kai Chou after a 10-year long research, and it has already favorably impacted more than 1 billion user experiences around the world. Now let us show you best practices on how we apply behavioral incentives for our customers through the lens of Octalysis. We’re applying all 8 core-drives to reward gamers.


3.1.1. Epic Meaning & Calling

This core-drive motivates players because they are doing something greater than themselves, or they were “chosen” to do something. A player who devotes a lot of time to maintaining a community, a forum or is helping to create value for others (think Wikipedia or Open Source projects).

Motivational drivers: Narrative, Elitism, Humanity hero, Revealed heart, Beginners luck, Destiny child, Creationist, a.o.

Example of Meaning from the game - Blackbox with Coca-Cola: Coca-Cola will match every dollar donated to game developer with $10 amount donated to “Water for People”.

Calling an epic meaning functionality from within your game would be like:

MonetizrSdk.showProductForTag("donate-water-for-people")

water_for_people


3.1.2. Development & Accomplishment

A core-drive that sees the player desiring to learn more in order to overcome challenges, make progress, develop skills, and eventually - overcome challenges. The word “challenge” here is very important, because giving out badges or trophies without a challenge is not meaningful at all.

Development & Accomplishment s are one of the easiest to design for points, badges and leaderboards.

Motivational drivers: Status points, Badges, Achievement symbols, Fixed action rewards, Earned points, Leaderboard, Progress bar, Quest list, Dessert oasis, High five, Crowding, Anticipation parade, Aura effect, Step-by-step overlay tutorial, Boss fights, a.o.

Example of Quest points from the game - Hatch-it Hatch-it is a puzzle game where a little robot has to hatch dinosaur eggs in order to save them from falling asteroids. Merch items are unlocked throughout the game, saving exclusive swag and bigger discounts for higher achievements. The more the user plays, the higher exclusivity product and discount he/she gets. At the final level called “winter”, the user can unlock really rare, one-of-a kind items.

Calling an accomplishment from within your game would be like:

MonetizrSdk.showProductForTag("unlocked-status-points")

hatch_it


3.1.3. Empowerment of Creativity & Feedback

Core-drive that sees when users are engaged in a creative process where they have to repeatedly figure things out and try different combinations. Players need to express their creativity and see results, receive feedback, and respond in turn. This is why playing with Legos and painting is fun in-and-of itself and often becomes Evergreen Mechanics, where a game-designer no longer needs to continuously add more content to keep the game fresh and engaging.

Motivational drivers: milestone unlocks, real-time control, evergreen combos, instant feedback, boosters, blank fills, plant pickers, poison pickers, a.o.

Example of Milestone unlocks from the app - Slopes Slopes is an app for tracking skiing and snowboarding activities. It uses smart recording functions, works without wi-fi or even cellular service and activities can be easily shared with friends and family. By skiing and/or snowboarding, players earn the right/opportunity to buy limited edition branded swag. Every ride unlocks a new level and new merchandise.

Calling an empowerment from within your game would be like:

MonetizrSdk.showProductForTag("unlocked-limited-edition-swag")

slopes


3.1.4. Ownership & Possession

Core-drive where the player feels intense motivation because they own something. When the player is motivated by ownership, there is a strong desire to both acquire items and to own even more. This deals with many virtual goods or virtual currencies within systems and the intrinsic desire to accumulate wealth. Also, if a person spends a lot of time customizing their profile or avatar, they automatically feel more ownership towards that too. Finally, this is also the core-drive that makes collecting stamps or puzzle pieces fun.

Motivational drivers: Exchangeable points, Virtual goods, Build from scratch, Alfred effect, Collection sets, Avatar, Protection, Recruiter burden, Monitor attachment, a.o.

Example of Ownership of the solved puzzles from the game - LazyPixel LazyPixel is a coloring puzzle game. Ownership of long collected puzzles now will be saved and worn in the real world.

Calling an ownership from within your game would be like:

MonetizrSdk.showProductForTag("collected-1-credit")

lazy_pixel


3.1.5. Social Influence & Relatedness

This core-drive incorporates all the social elements that drive people, including: mentorship, acceptance, social responses, companionship, as well as competition and envy. When you see a friend that is amazing at some skill or owns something extraordinary, you become driven to reach the same level. This is the drive where we draw closer to other people, places, or events that we can relate to. For example, it could be a product that reminds the player of their childhood. The sense of nostalgia would likely increase the odds of a player buying the game swag. Many companies are optimizing their online social strategies nowadays to take advantage of this drive.

Motivational drivers: Friending, Social treasure, Gifting, SeeSaw bump, Group quests, Tout flags, Brag, a.o.

Example of Social status influence from the game - Live Blackjack 21 Live Blackjack 21 is a live mobile multiplayer Blackjack / casino game. The game has a live chat, the possibility to challenge friends and also customize game avatars. Each game is a new mix of players, keeping it social. Just like karate, players earn more exclusive “belts” aka game hoodies, to show their skill level to their peers. Of course, the black belt or the premium gold hoodie is the best one.

Calling a relatedness from within your game would be like:

MonetizrSdk.showProductForTag("right-to-brag-available")

blackjack


3.1.6. Scarcity & Impatience

Core-drive with a simple premise — the player wants to have something for the fact alone that they can’t have it yet. Many games have Appointment Dynamics (come back 2 hours later to get your reward) – the fact that people can’t get something right now motivates them to think about it all day long.

Motivational drivers: Appointment dynamics, Magnetic caps, Dangling, Prize pacing, Options pacing, Last mile drive, Countdown timer, Torture breaks, Moats, The big burn, a.o.

Example of Impatience from the game - Nitro Nation Nitro Nation is a car racing game. Each race the player wins provides parts to upgrade the car. As car upgrades get better the races get harder. Nitro Nation and Audi combined efforts and offered players a weekend challenge. TOP 20 players won prizes by Audi but due to high participation, getting and staying in leaderboard took some serious car racing.

Invoking impatience from within your game would be like:

MonetizrSdk.showProductForTag("come-back-in-two-hours")

nitro


3.1.7. Unpredictability & Curiosity

A constant harmless desire of wanting to find out what will happen next. If you don’t know what’s going to happen, your brain is engaged and you think about it often. People watch movies or read novels because of this drive. This drive is also the primary factor behind gambling addiction. Also, this core drive is utilized whenever a company runs a sweepstake or lottery program to engage users. The very controversial Skinner Box experiments, where an animal irrationally presses a lever frequently because of unpredictable results, are exclusively referring to the core-drive of Unpredictability & Curiosity.

Motivational drivers: Glowing choice, Mini quests, Visual storytelling, Easter eggs, Random rewards, Obvious wonder, Rolling rewards, Evolved UI, Sudden rewards, Oracle effect, a.o.

Example of Curiosity from the game - Blackbox Blackbox is series of puzzles that are ever-growing and all involve not touching the screen. Game notifications are used for various accomplishments to drive curiosity. Just when the player thinks he/she has done it all, a secret surprise comes along. Even the box that t-shirts are delivered in, is a part of an elaborate Blackbox Easter egg.

Creating unpredictability from within your game would be like:

MonetizrSdk.showProductForTag("an-easter-egg-was-created")

blackbox


3.1.8. Loss & Avoidance

Core-drive is based upon the avoidance of something negative happening. On a small scale, it could be to avoid losing previous work. On a larger scale, it could be to avoid admitting that everything you did up to this point was useless because you are now quitting. Opportunities that are fading away have a strong utilization of this emotional drive, because people feel like if they didn’t act immediately, they would lose the opportunity to act forever.

Motivational drivers: Limited time offer, Sunk cost prison, Progress loss, Rightful heritage, Evanescence opportunity, Status quo sloth, Scarlet letter, Visual grave, FOMO punch, a.o

Example of Loss and avoidance from the game - Blackbox Blackbox is series of puzzles that are ever growing, that all involve not touching the screen. Three days to get where everybody in the game could purchase a shirt that is available only to the elite players. This was supported with a price booster that would disappear in three days.

Avoiding a loss from within your game would be like:

MonetizrSdk.showProductForTag("you-avoided-problem-have-a-t-shirt")

blackbox_loss_avoidance


You're done!

You have successfully integrated Monetizr. You can now test it by making a test order.


Contact Information

If you have other questions, book a meeting.

I’m also available at 📧 martins@themonetizr.com 📱🇺🇸: +1 917-943-8791

martins

Got questions? Contact me!

Martins