Skip to content Skip to main navigation Skip to footer

How to use Branded Mini Games in iOS App

No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language, in any form or by any means, electronic, mechanical, photocopying, recording, or otherwise, without prior written permission from Emoji Games.

All copyrights, confidential information, patents, design rights and all other intellectual property rights whatsoever in nature contained herein are and shall remain the sole and exclusive property of Emoji Games Solutions GmbH. The information furnished herein is believed to be accurate and reliable.

However, no responsibility is assumed by Emoji Games for its use, nor for any infringements of patents or other rights of third parties resulting from its use.

The Branded Mini-Games logo is a registered trademark of Emoji Games Solutions GmbH.

1. Introduction

1.1. Purpose

The purpose of this document is to guide developers who want to integrate a Game provided by Emoji Games into your iOS game/app.

1.2. Environment

  • Development tools on Mac or MacBook Pro: XCode 6.2, target 6.0.
  • Operating system on mobile device : iOS 6.0 or higher.
  • The event_info.dat file created by BMG Event Creator tool (provided by Emoji Games).

event_info.dat file must be uploaded onto the server and you have to get the direct URL of that file.

1.3. Overview

2. Configuration

2.1 Get event_info.dat file

To obtain the event_info.dat file, please contact the Emoji Games tech team at support@brandedminigames..com.

2.2 Upload event_info.dat file to server

After getting the event_info.dat file, you should upload it to your server and get the direct URL of it.

E.g: http://brandedminigames.com/BMGSDK_Demo/event_info.dat

2.3 Modify Info.plist

2.3.1 Adding one more property for url of event data file

Property name : BMGEventDataUrl (up to client’s naming)

Property value : this value is the URL to which you uploaded the event data file

modify_info_ios
2.3.2. Adding another property for url scheme

Property name : BMGScheme

Property value : The url scheme for the current campaign.

Ex:

bmgscheme_ios

URL scheme must be the same as the one you registered on the campaign page in Studio site:

2.3.3. Adding url type

A URL type item should be like the example below:

adding_url-t_type

3. Implementation

3.1 Download and Decode event_info.dat file from your server

3.1.1. Download Event data file

First, you must have the URL of dat file that contains all branded mini game event.

E.g: http://brandedminigames.com/BMGSDK_Demo/event_info.dat

If you would like to use game demo events for testing, please set the URL to the one above. This is the event information data file for game demo events. Or you can download this event_info.dat file and then upload it on your server. The URL will be your server URL.

In viewDidLoad method of main viewcontroller, should make a method to get event data from the server then parser and save them to memory.

NSData * d = [NSData dataWithContentsOfURL: [NSURL URLWithString: self.eventInfo] options: NSDataReadingUncached error: nil];
if (d == nil) {
  NSException * exception = [NSException exceptionWithName: @ “Can not get the event data!”
    reason: @ “Wrong URL of event data file or no connection!”
    userInfo: nil
  ];
  @throw exception;
}
3.1.2. Decode data

When we receive byte array from data file in the server, we can not use it because this byte array has been encoded.

  • The algorithm is “AES-128”
  • Key is “brandedminigames”

Use this code to decode the data:

NSString * key = @ “brandedminigames”;
NSData * h = [d AES128DecryptedDataWithKey: key];
if (h == nil) {
  NSException * exception = [NSException exceptionWithName: @ “Data can not be decrypted!”
    reason: @ “Missing -ObjC value for <Other Linker Flags> property!”
    userInfo: nil
  ];
  @throw exception;
}

NSError * err;
NSArray * data = [NSJSONSerialization JSONObjectWithData: h options: kNilOptions error: & err];
if (err != nil) {
  NSException * exception = [NSException exceptionWithName: @ “Wrong format!”
    reason: @ “Format of data is wrong when parsing to JSon data!”
    userInfo: nil
  ];
  @throw exception;
}
3.1.3. Parser data from json data
for (NSObject * obj in data) {
  // [obj valueForKey:@”campaignId”];
  // [obj valueForKey:@”start”];
  // [obj valueForKey:@”end”];
  // [[obj valueForKey:@”status”] integerValue];
  // [obj valueForKey:@”url”];
  // [obj valueForKey:@”title”];  
  // [obj valueForKey:@”desc”];
  // [obj valueForKey:@”imgBanner”];
  // [obj valueForKey:@”maxScore”];
}

Because you can create many events using BMG Event Data Tool, the event information that you decoded from binary data to JSON data is an array list. You can select the specific event in the array list and use it. Specifically, it is a JSON Array that contains one or many JSON Objects. If there are many events, you could use ArrayList to save them.

JSON Object information:

Field nameDescription
startEvent start time. Format ‘MM/dd/yyyy’
endEvent end time. Format ‘MM/dd/yyyy’
statusEvent status.0: Disable1: Enable
urlEvent game url
titleEvent title
descEvent description
maxScoreMaximum possible score from this event game
campaignIdID of current campaign

3.2. Build URL from original URL in memory

After retrieving and decoding data from event_info.dat file is complete, in order to play the branded mini game you must build a URL based on the URL received in the previous step:

NSString  *url = [obj valueForKey:@”url”];

The new url looks like:

//add parameter to url

NSString *bundleID = [[NSBundle mainBundle] bundleIdentifier];//

url = [NSString stringWithFormat:@”%@&app_user=%@&route=%@”, url, user_id, bundleID];

//add os detect

url = [NSString stringWithFormat:@”%@&ostype=ios”, url];

“app_user”: is string format. This should be an email address or ID of the user that will be taken from your application after the user has logged in. This information will be used to identify each user that has joined the Event mini game, and through this parameter the winner can be detected at the end of the Event. If the user is not logged in or has no account, you should generate a random value. This parameter is mandatory. E.g random value:

NSString * user_id = [
  [NSUserDefaults standardUserDefaults] stringForKey: @ “BMGLibGuestUser”
];
if (user_id == nil || [user_id isEqualToString: @ “”]) {
  NSString * rnd_ID = @ “”;
  for (int i = 0; i < 10; i++) {
    int t = arc4random() % 10;
    rnd_ID = [rnd_ID stringByAppendingFormat: @ “%d”, t];
  }
  user_id = [NSString stringWithFormat: @ “guest_%@”, rnd_ID];
  [
    [NSUserDefaults standardUserDefaults] setValue: user_id forKey: @ “BMGLibGuestUser”
  ];
}

3.3. Play the Game on the webview

self.webView = [[UIWebView alloc] initWithFrame:self.view.bounds];
 
 
self.webView.delegate = self;
self.webView.scalesPageToFit = YES;
self.webView.dataDetectorTypes = UIDataDetectorTypeAll;
 
 
[self.view addSubview:self.webView];
[self.webView loadRequest:[NSURLRequest requestWithURL:[NSURL URLWithString:self.gameUrl]]];

3.4. Play the game using Safari browser

[[UIApplication sharedApplication] openURL:[NSURL URLWithString:url]];

3.5. Handle inter-app communication

Override the following methods in your app delegate class (default is in AppDelegate.m file):

AppDelegate.m –
  (BOOL) application: (UIApplication * ) application didFinishLaunchingWithOptions: (NSDictionary * ) launchOptions {
    return YES;
  }

  –
  (BOOL) application: (UIApplication * ) application willFinishLaunchingWithOptions: (NSDictionary * ) launchOptions {
    return YES;
  }

These 2 methods must return YES.

Override and add code to the following method:

AppDelegate.m –
  (BOOL) application: (UIApplication * ) application openURL: (NSURL * ) url sourceApplication: (NSString * ) sourceApplication annotation: (id) annotation {

    NSString * bmgScheme = [
      [NSBundle mainBundle] objectForInfoDictionaryKey: @ “BMGScheme”
    ];

    if ([
        [url scheme] isEqualToString: bmgScheme
      ]) {
      //get score and rank from url
      NSString * st = url.absoluteString;

      //score
      unsigned long pos1 = [st rangeOfString: @ “score=”].location;
      pos1 += 6; /*length of “score=” is 6*/
      NSString * score = @ “”;
      while (![
          [st substringWithRange: NSMakeRange(pos1, 1)] isEqualToString: @ “&”
        ]) {
        score = [NSString stringWithFormat: @ “%@%@”, score, [st substringWithRange: NSMakeRange(pos1, 1)]];
        ++pos1;
      }
      NSLog(@ “score: %@”, score);

      //rank
      pos1 = [st rangeOfString: @ “rank=”].location;
      pos1 += 5; /*length of “rank=” is 5*/
      NSString * rank = @ “”;
      while (pos1 <= st.length – 1) {
        rank = [NSString stringWithFormat: @ “%@%@”, rank, [st substringWithRange: NSMakeRange(pos1, 1)]];
        ++pos1;
      }
      NSLog(@ “rank: %@”, rank);

    }

    return YES;
  }

The above code handles inter-app communication between Safari and the app, or between the webview and the app. After the user clicks the “close” button in the leaderboard page, this method will be called and bring the app to the foreground.

3.6. How to give a reward to your application user based on event game score

If your application or service uses its own point system (such as score, mileage or virtual money), you can convert the user’s score to your application’s own point system. There are two ways to convert the event game score:

Way 1)

– The maxScore can be used to get the maximum possible score that can be obtained in the current event game. The max score will be needed to convert the event game score to your own point system. Please refer to the table below:

Allowed max reward point in your application. (A)Max score in the specific event game. (B)The constant to convert.(A / B = C)User’s scorein event game (D)Converted reward pointin your application (C * D)
1004,0000.0253,60090
4501,5000.3350105
10,0002,00051,3506,750

Way 2)

– The score range in the specific event game can be adjusted by Emoji Games’ Service Operation team. If you would like to adjust the score range of a specific event game in order to use it directly for your reward point system, please contact Emoji Games’ Service Operation team at support@brandedminigames.com.

Submit a query

Leave us a message