Quickstart

Compatibility

The Megacool SDK supports iOS 7+, but GIF capturing is only supported on iOS 8+.

Latest SDK version

3.3.7

Overview

The Megacool SDK provides two ways to boost user growth:

  • Incentivize users to refer their friends
  • Make it easy to share GIF moments

This quickstart guide will help you set up the basic functionality of the Megacool SDK:

Step 1: Set up your app on the dashboard
Step 2: Install the Megacool SDK
Step 3: Set up referrals
Step 4: Add media

Step 1: Set up your app on the dashboard

Set up your app on the dashboard to receive the required keys for the SDK. After you're done, refresh this page to see your keys in this guide.


Step 2: Install the Megacool SDK

  1. Add pod 'Megacool' to your Podfile
  2. Run pod install
  3. Verify that you got version 3.3.7, then you're all set! 🎉
  1. Download the framework
  2. Extract the files (double-click in Finder usually does the trick)
  3. Drag & drop the Megacool.Framework directory into Xcode under Frameworks in the directory
    • NB: NOT among the 'Linked Frameworks and Libraries'
      • Shit, I just did that:
        1. Delete it from 'Linked Frameworks and Libraries'
        2. Open the Project in Finder
        3. Delete the framework again
  4. Make sure to check off 'Copy items if needed' in the drop down
  5. Click 'Finish'.

The Megacool SDK requires the following frameworks to be linked to your project:

  • CoreGraphics
  • CoreMedia
  • Foundation
  • libz1.2.5.tbd
  • Security
  • UIKit
  • SafariServices (recommended)
  • Social (for Twitter support)
  • Account (for Twitter support)

To link with the frameworks:

  1. Click on your project
  2. Open the 'General' tab
  3. 'Linked Frameworks and Libraries' is displayed on the bottom of the page

  1. Press the '+' symbol below 'Linked Frameworks and Libraries'
  2. Type the name of the missing framework(s)
  3. Highlight the correct framework, click "Add"

Before getting started you need to set a few IDs and links.

URL Scheme for deep linking

  1. Select your Project
  2. Go to the 'Info' tab
  3. Go to the bottom of the page to find 'URL Schemes'
  4. Click '+' to add new URL Scheme
  5. Add your URL Scheme: YOUR_URL_SCHEME
  6. Make sure to leave the rest blank
  1. Select your project
  2. Open the ‘Capabilities’ tab
  3. Open ‘Associated Domains’
  4. Turn it ‘ON’
  5. Click ‘+’ to add new domain
  6. Write applinks:mgcl.co
  7. Make sure all ‘steps’ are approved
    1. If "fix issues" appear, press Ok to fix them
    2. If that doesn't help, check the following:
      1. That you have the right team selected
      2. That your Bundle Identifier of your Xcode project matches the one used to register the App Identifier
  8. Make sure an entitlement file is added to your project

Initialize the SDK

We strongly recommend to initialize the Megacool SDK in your AppDelegate's application:didFinishLaunchingWithOptions: method so that it'll be set for the entire lifecycle of your app.

Open AppDelegate.m file:

#import <Megacool/Megacool.h>
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Override point for customization after application launch.
[Megacool startWithAppConfig:@"YOUR_IOS_KEY"];
return YES;
}

In addition, add the following methods to handle deep/universal link requests in your AppDelegate. Either by using this macro:

MEGACOOL_DEFAULT_LINK_HANDLERS

Or by adding the code for each link handler so you can customize them:

/*iOS 9 deep link handler*/
- (BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
options:(nonnull NSDictionary<NSString *, id> *)options {
[[Megacool sharedMegacool] openURL:url options:options];
return YES;
}
/*iOS 4-8 deep link handler */
- (BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication
annotation:(id)annotation {
[[Megacool sharedMegacool]
openURL:url
sourceApplication:sourceApplication];
return YES;
}
/*iOS 9+ Universal Link handler */
- (BOOL)application:(UIApplication *)application
continueUserActivity:(NSUserActivity *)userActivity
restorationHandler:(void (^)(NSArray *restorableObjects))restorationHandler {
return [Megacool continueUserActivity:userActivity];
}
/* Background upload/download handler (gif upload and fallback image download) */
- (void)application:(UIApplication *)application
handleEventsForBackgroundURLSession:(NSString *)identifier
completionHandler:(void (^)(void))completionHandler {
[Megacool
handleEventsForBackgroundURLSession:identifier
completionHandler:completionHandler];
}

Step 3: Set up referrals

Make it easy for players to share your game to their friends. Incentivize players by rewarding them for each share they send that leads to a new friend installing the game.

Expand startWithAppConfig:andEventHandler to receive the callback from the server when a share has been opened on a new device:

[Megacool startWithAppConfig:@"YOUR_IOS_KEY" andEventHandler:^(NSArray<MCLEvent *> * events) {
for (MCLEvent* event in events) {
switch (event.type) {
// This device has received a share to the app
case MCLEventReceivedShareOpened:
// Check if this is a new install
if (event.isFirstSession) {
// Receiver installed the app for the first time
NSLog("This device installed the app.");
}
break;
// A share sent from this device has been opened
case MCLEventSentShareOpened:
// Check if this is a new install
if (event.isFirstSession) {
// Receiver installed the app for the first time
NSLog("Your friend installed the app. Here's your reward!");
}
break;
}
}
}];

Add a referral button

Add a referral button that lets players refer their friends by sharing a link to the game. Call the following method when pressed:

- (void)share {
[self.view addSubview:self.spinner];
[self.spinner startAnimating];
self.spinner.center = self.view.center;
[self performSelector:@selector(shareAfterSpinner)
withObject:nil
afterDelay:.1];
}
- (void)shareAfterSpinner {
[[Megacool sharedMegacool] presentShare];
[self.spinner stopAnimating];
[self.spinner removeFromSuperview];
}
UX win

Why the spinner in the example above? presentShare wraps some Apple APIs that will block for some time on certain devices, starting a spinner first ensures that when the UI gets blocked on these devices there's something there to let users know things are happening. The 0.1s delay in the call to performSelector:withObject:afterDelay is crucial to make this work reliably.

Note: For iPad, you need to specify where the popover will appear from (PopOver from a source view, e.g. a button).

[[Megacool sharedMegacool] presentShareWithConfig:^(MCLShareConfig *config) {
config.sourceView = buttonView;
}];

If you've reassigned the window.rootViewController please add the preferred ViewController to present the modal view from:

[[Megacool sharedMegacool]
presentShareWithConfig:nil
inViewController:yourViewController];

This opens a share modal with a link to your game that lets players refer friends through any channel available on their device.

Read more about referrals and how to test it here.


Step 4: Add media

Include this in the file you would like to record from:

#import <Megacool/Megacool.h>

Add a recording to the share

To increase the share-to-install conversion rate, make the share more appealing by adding a recording of the game play. When the game session begins, start a new recording:

[[Megacool sharedMegacool] startRecording:self.view];

The recording will keep a buffer of the last 5 seconds by default. Old frames get overwritten by new frames.

End the recording when the game session is over by calling:

[[Megacool sharedMegacool] stopRecording];

The next time you call presentShare, the latest recording will be included in the share together with the referral link.

Read more about how to customize recordings here.

Add fallback media

Fallback media is used in cases when there’s no recording or if the recording has failed. The fallback media can be JPEG, PNG, GIF or even MP4. For historical reasons, the SDK refers to it as FallbackImage.

Fallback media can be given either as UIImages or NSURLs, depending on what is easiest for you. To set fallback media as a NSURL:

NSURL *fallbackImageUrl = [NSURL
fileURLWithPath:[[NSBundle mainBundle]
pathForResource:@"fallbackImage"
ofType:@"png"]];
[[Megacool sharedMegacool] presentShareWithConfig:^(MCLShareConfig *config) {
config.fallbackImageUrl = fallbackImageUrl;
}];

If you prefer to set it as a UIImage, that's entirely kosher, but since UIImages cannot hold a GIF you cannot use this if you want animated media:

[[Megacool sharedMegacool] presentShareWithConfig:^(MCLShareConfig *config) {
config.fallbackImage = [UIImage imageNamed:@"fallbackImage.png"];
}];

When choosing your media file please keep in mind that there's a size limit for some social media platforms, so try to stay below 3MB.

Note: Certain platforms do not support uploading media files, so it has to be set manually from the server side. Please contact us if you wish to add support for a missing platform.

Do a test run!

Build your project to a device and run it!


Notice

We strongly believe in not crashing your apps. But, since networking and computers are inherently unreliable, stuff sometimes fails. To prevent your users from noticing these failures, you should always be prepared for our API calls to return nil or other signals of failure, and have a plan if that happens. This can happen if your app runs out of memory, disk is full, or some other bug is present which prevents us from delivering the expected value from our API calls. We strongly believe in the philosophy of progressive enhancement, and this is your best way for interacting with our API as well. In practice, always assume that our tools fail, but rejoice when they are working as promised.

Note: In the case of severe performance regressions, bugs on certain platforms, we can disable some of our features remotely. This would have the same effect as a feature not working. Thus it's easy to test the error conditions locally.