Quickstart

Supported OS

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

SDK

2.4.0

Important 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.

0 Configuration

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

0.1 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

1 Installation

The easiest way to get started with Megacool on iOS is by installing through CocoaPods. The pod is called "Megacool". Since you're awesome you get to go directly to step 2.

1.1 Manual installation

1.1.1 Link frameworks

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"

1.1.2 Install Megacool

The Megacool framework can be copied directly into your app:

  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
    1. NB: NOT among the 'Linked Frameworks and Libraries'
      1. 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'.

2 Start coding!

2.1 Initialize the framework

Initialize Megacool, we strongly recommend doing this 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:@"YourAppConfig"];
return YES;
}

In addition add these 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 sharedMegacool]
continueUserActivity:userActivity];
}
/* Background upload/download handler (gif upload and fallback image download) */
- (void)application:(UIApplication *)application
handleEventsForBackgroundURLSession:(NSString *)identifier
completionHandler:(void (^)())completionHandler {
[[Megacool sharedMegacool]
handleEventsForBackgroundURLSession:identifier
completionHandler:completionHandler];
}

2.2 Record your view

It's time to record and generate a GIF! There are two possible ways to record:

a. Time recording: Continuously record the screen or

b. Capturing frames: Capture frame by frame

We recommend exploring time recording for real-time games, e.g. platformers like Flappy Bird. Capturing frames are best suited for turn-based games where it makes more sense to capture each move the user makes, e.g. chess.

Include this in the file you would like to record from

#import <Megacool/Megacool.h>

2.2.1a Time recording

Add the following line of code where you want to start a recording:

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

The recording will by default keep a buffer of the last 5 seconds. Old frames get overwritten by new frames. You can customize this later.

To stop a recording, add the following line of code:

[[Megacool sharedMegacool] stopRecording];

2.2.1b Capture frames

Capture each frame of the recording, e.g. on each user tap:

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

By default max 50 frames will be captured. If it exceeds 50 frames, old frames are overwritten until stopRecording gets called to reset it. Add the following line of code to stop a recording:

[[Megacool sharedMegacool] stopRecording];

2.2.2 Open modal view to share the GIF

Add the following line of code to share the recorded GIF. A modal share view will pop up with the option to share to different channels.

[[Megacool sharedMegacool] presentShare];

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

[[Megacool sharedMegacool]
presentShareWithConfig:@{kMCLConfigSourceViewKey:buttonView}];

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

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

2.3 Do a test run!

Do a test run to see if the GIF capturing and sharing work. Send a message to yourself and verify that the link opens the app again.

The following GIF shows what a share modal view looks like for the user. The user is able to select a channel to share the GIF with:



Well done, this should be enough to get you started! To optimize the recording and share experience, continue to customization.