iPhone iOS App

No part of this help document may be reproduced, transmitted, copied, stored in a retrieval system, or translated into any language in any form or by any means, electronic, mechanical, photocopying, recording, etc., without the prior written permission of Emoji Games.

All copyrights, confidential information, patents, design rights, and all other intellectual property rights contained herein are the sole and exclusive property of Emoji Games. The information provided herein is considered accurate and reliable.

Furthermore, Emoji Games is not responsible for the use of the game or any third-party patent or other rights infringement resulting from it.

1. Introduction

1.1. Purpose

The purpose of this document is for developers who want to integrate games provided by Emoji Games into iOS (iPhone) games/apps.

1.2. Preparation

• Development tools for Mac or MacBook Pro: XCode 6.2, Target 6.0.

• Operating system of mobile devices: iOS 6.0 or higher.

• event_info.dat file created in the BMG Event Creator tool (provided by Emoji Games).

You need to upload the event_info.dat file to the server and obtain the direct URL of the file.

1.3. Overview

2. Configuration

2.1. Import the event_info.dat file

For inquiries about the event_info.dat file, please contact [e-mail].

2.2. Upload the event_info.dat file to the server

After receiving the event_info.dat file, you need to upload it to the server and obtain the direct URL.

Example: http://brandedminigames.com/BMGSDK_Demo/event_info.dat

2.3. Modify Info.plist

2.3.1. Add one more URL property for the event data file

Property name: BMGEventDataUrl (up to client name specification)

Property value: This value is the URL where the event data file was uploaded.

2.3.2. Add another property for the URL scheme

Property name: BMGScheme

Property value: This is the URL scheme of the current campaign.

Example)

The URL scheme must be the same as the one registered on the campaign page of the Studio site.

2.3.3. Add URL type

The URL type entry should be as shown in the example below.

3. Implementation

3.1. Download and decode the event_info.dat file from the server

3.1.1. Download the event data file

First, you need to have the URL of the dat file containing all branded mini-game events.

Example: http://brandedminigames.com/BMGSDK_Demo/event_info.dat

To use the game demo event for testing, set the URL to the URL above. This is the event information data file for the game demo event. Alternatively, you can download this event_info.dat file and upload it to the server. The URL will be the server URL.

In the viewDidLoad method of the main viewcontroller, you need to create a method that fetches event data from the server, parses it, and stores it in 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. Data decoding

When you receive a byte array from the data file on the server, this byte array is encoded and cannot be used.

• The algorithm is "AES-128."

• The 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 of 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”];
}

Since you can create many events using the BMG Event Data Tool, the event information decoded from binary data to JSON data is an array list. You can select and use a specific event from the array list. In particular, it is a JSON array containing one or more JSON objects. If there are many events, you can store them using ArrayList.

JSON object information:

Field name	Description
start	Event start time. Format ‘MM/dd/yyyy’
end	Event end time. Format ‘MM/dd/yyyy’
status	Event status.0: Disable1: Enable
url	Event game url
title	Event title
desc	Event description
maxScore	Maximum possible score from this event game
campaignId	ID of current campaign

3.2. Build URL from the original URL in memory

After retrieving and decoding data from the event_info.dat file, you need to build a URL based on the URL received in the previous step to play the branded mini-game.

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

The new URL is as follows.

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": This is a string format. This should be the user's email address or ID obtained from the application after the user has logged in. This information is used to identify each user who participated in the event mini-game and can become a winner through this parameter. It is detected at the end of the event. If the user is not logged in or does not have an account, you need to generate a random value. This parameter is required. Example: 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 in a 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 the Safari browser

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

3.5. Handling app-to-app communication

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

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

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

These two methods should 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 code above handles "Safari and app" or "webview and app" communication. When the user clicks the "Close" button on the leaderboard page, this method is called to bring the app to the foreground.

3.6. How to provide rewards to application users based on event game scores

If your application or service uses its own point system (e.g., scores, mileage, or virtual currency), you can convert the user's score to the application's own point system. There are two ways to convert event game scores.

Method 1)

• maxScore can be used to obtain the maximum score that can be obtained in the current event game. To convert the event game score to your own point system, you need the maximum score. Refer to the table below.

A	B	(A / B = C)	D	(C * D)
Maximum reward points allowed in the application	Maximum score of a specific event game	Constant to be converted	User's score in the event game	Converted reward points in the application
100	4,000	0.025	3,600	90
450	1,500	0.3	350	105
10,000	2,000	5	1,350	6,750

Method 2)

• The score range of a specific event game can be adjusted by the Emoji Games service operation team. If you want to adjust the score range of a specific event game for direct use in the reward point system, please contact the Emoji Games service operation team at [e-mail].