Integration guide for iOS

Start selling your own game merchandise

Version: 2

Date: 16/07/2019

Process:


Additional information

Useful links: * [Github project] (https://github.com/themonetizr/monetizr-ios-sdk) * [API reference] (https://api3.themonetizr.com/docs) * [API Integration guide] (https://docs.themonetizr.com/api/index.html)

Dependencies


Step 1. Installation

Requires iOS 10.0+

Installing Monetizr iOS is a simple process, we do provide couple of variants:

  • using CocoaPods
pod 'Monetizr', '~> 3.0'
  • Manual process:
Copy "Monetizr-SDK" folder to your project and resolve dependencies

Step 2. Setting up and using SDK

2.1. In applicationDidFinishLaunching(_:) do the initialization with token provided to you. Example token 4D2E54389EB489966658DDD83E2D1

Monetizr.shared.token = String

Optionally you can set language for your products

Monetizr.shared.setLanguage(language: "en_EN")

2.2. Import “Monetizr” to your project

import Monetizr

2.3. Show product

Monetizr.shared.getProductForTag(tag: String, show: Bool) { success, error, product in ()}

Example product tags that are provided with example api key are:

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

Step 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:

Monetizr.shared.getProductForTag(tag: "donate-water-for-people", show: true) { success, error, product in ()}

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:

Monetizr.shared.getProductForTag(tag: "unlocked-status-points", show: true) { success, error, product in ()}

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:

Monetizr.shared.getProductForTag(tag: "unlocked-limited-edition-swag", show: true) { success, error, product in ()}

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:

Monetizr.shared.getProductForTag(tag: "collected-1-credit", show: true) { success, error, product in ()}

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:

Monetizr.shared.getProductForTag(tag: "right-to-brag-available", show: true) { success, error, product in ()}

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:

Monetizr.shared.getProductForTag(tag: "come-back-in-two-hours", show: true) { success, error, product in ()}

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:

Monetizr.shared.getProductForTag(tag: "an-easter-egg-was-created", show: true) { success, error, product in ()}

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:

Monetizr.shared.getProductForTag(tag: "you-avoided-problem-have-a-t-shirt", show: true) { success, error, product in ()}

blackbox_loss_avoidance


Step 4. (Optional) Manual usage of Monetizr.shared with custom product views

4.1. Open product view

func openProductViewForProduct(product: Product, tag: String)

4.2. Checkout variant for product with tag

func checkoutSelectedVariantForProduct(selectedVariant: PurpleNode, tag: String, completionHandler: @escaping (Bool, Error?, Checkout?) -> Void)

4.3. Increase impression count for session

func increaseImpressionCount()

4.4. Increase click count for session

func increaseClickCountInSession()

4.5. Increase checkout count for session

func increaseCheckoutCountInSession()

4.6. Get session duration in seconds

func sessionDurationSeconds() -> Int

4.7. Get session duration in miliseconds

func sessionDurationMiliseconds() -> Int

4.8. Telemetrics - Create a new entry for impression

func impressionvisibleCreate(tag: String?, fromDate:Date?, completionHandler: @escaping (Bool, Error?, Any?) -> Void)

4.9. Telemetrics - Create a new entry for reward clicked

func clickrewardCreate(tag: String?, completionHandler: @escaping (Bool, Error?, Any?) -> Void)

4.10. Telemetrics - Create a new entry for design data

func designCreate(numberOfTriggers: Int?, funnelTriggerList: String?, completionHandler: @escaping (Bool, Error?, Any?) -> Void)

4.11. Telemetrics - Create a new entry for dismissal of view

func dismissCreate(tag: String?, completionHandler: @escaping (Bool, Error?, Any?) -> Void)

4.12. Telemetrics - Create a new entry for installation of application

func installCreate(deviceIdentifier: String?, completionHandler: @escaping (Bool, Error?, Any?) -> Void)

4.13. Telemetrics - Create a new entry for update

func updateCreate(deviceIdentifier: String, bundleVersion: String?, completionHandler: @escaping (Bool, Error?, Any?) -> Void)

4.14. Telemetrics - Create a new entry for first impression shown to player

func firstimpressionCreate(sessionDuration: Int?, completionHandler: @escaping (Bool, Error?, Any?) -> Void)

4.15. Telemetrics - Create a new entry for players behaviour

func playerbehaviourCreate(deviceIdentifier: String, gameProgress: Int?, sessionDuration: Int?, completionHandler: @escaping (Bool, Error?, Any?) -> Void)

4.16. Telemetrics - Create a new entry for purchase

func purchaseCreate(deviceIdentifier: String, triggerTag: String?, productPrice: String?, currency: String?, country: String?, city: String?, completionHandler: @escaping (Bool, Error?, Any?) -> Void)

4.17. Telemetrics - Create a new entry for sessions end event

func sessionEnd(deviceIdentifier: String, startDate: String?, endDate: String?, completionHandler: @escaping (Bool, Error?, Any?) -> Void)

4.18. Telemetrics - Create a new entry for session start

func sessionCreate(deviceIdentifier: String, startDate: String?, completionHandler: @escaping (Bool, Error?, Any?) -> Void)

4.19. Telemetrics - Create a new entry for encounter

func encounterCreate(triggerType: String?, completionStatus: Int?, triggerTag: String?, levelName: String?, difficultyLevelName: String?, difficultyEstimation: Int?, completionHandler: @escaping (Bool, Error?, Any?) -> Void)

4.20. Telemetrics - Create a new entry for first impression click

func firstimpressionclickCreate(firstImpressionClick: Int?, completionHandler: @escaping (Bool, Error?, Any?) -> Void)

4.21. Telemetrics - Create a new entry for gathering information for first impression shown and time until first checkout

func firstimpressioncheckoutCreate(firstImpressionCheckout: Int?, completionHandler: @escaping (Bool, Error?, Any?) -> Void)

4.22. Telemetrics - Create a new entry for impression until purchase event

func firstimpressionpurchaseCreate(firstImpressionPurchase: Int?, completionHandler: @escaping (Bool, Error?, Any?) -> Void)

You're done!

You have successfully integrated Monetizr SDK. 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