Megacool

Returns the singleton instance of Megacool. Must be used to call the Megacool methods.

Initializes the SDK. Get your app config from your Megacool Dashboard.

Initializes the SDK with a callback handler for events. Get your app config from your Megacool Dashboard.

There are 3 main events to handle:

• MCLEventLinkClicked: The app was opened from a link click. MCLEvent.type is MCLEventLinkClicked and event.data contains the path, query, referralCode and full URL, to send the user to the right scene. A request is sent to the server asap, and a MCLEvent with type receivedShareOpened will be passed to the callback with the associated share.

Note that if you are using any other SDKs alongside Megacool, MCLEventLinkClicked events might also be sent for URLs that were intended for the other SDKs. Since these events are intended for navigation within the app, you should validate that the path makes sense before routing the user to it, otherwise you can probably just ignore this event as the other SDKs will probably handle it.

• MCLEventReceivedShareOpened: When a shared link is clicked to either open or install the app, the eventHandler will receive the MCLEvent from the server. The MCLEvent.type is MCLEventReceivedShareOpened. isFirstSession is a boolean telling if the app was opened for the first time (new install) or just opened. The MCLShare is the object that was sent to this user.

• MCLEventSentShareOpened: When a shared link is clicked by another user and the app opens, a MCLEvent will be triggered. The event.type is MCLEventSentShareOpened, and the event contains the share object that was sent from this user. It also indicates if it was a first session and the event.data contains the other users referral code MCLEventDataReceiverReferralCode so you can match the users on your own.

Initializer dedicated for wrappers.

There are 3 main events to handle:

• MCLEventLinkClicked: The app was opened from a link click. MCLEvent.type is MCLEventLinkClicked and event.data contains the path, query, referralCode and full URL, to send the user to the right scene. A request is sent to the server asap, and a MCLEvent with type receivedShareOpened will be passed to the callback with the associated share.

Note that if you are using any other SDKs alongside Megacool, MCLEventLinkClicked events might also be sent for URLs that were intended for the other SDKs. Since these events are intended for navigation within the app, you should validate that the path makes sense before routing the user to it, otherwise you can probably just ignore this event as the other SDKs will probably handle it.

• MCLEventReceivedShareOpened: When a shared link is clicked to either open or install the app, the eventHandler will receive the MCLEvent from the server. The MCLEvent.type is MCLEventReceivedShareOpened. isFirstSession is a boolean telling if the app was opened for the first time (new install) or just opened. The MCLShare is the object that was sent to this user.

• MCLEventSentShareOpened: When a shared link is clicked by another user and the app opens, a MCLEvent will be triggered. The event.type is MCLEventSentShareOpened, and the event contains the share object that was sent from this user. It also indicates if it was a first session and the event.data contains the other users referral code MCLEventDataReceiverReferralCode so you can match the users on your own.

Handle background upload/download tasks

This is necessary to properly handle uploading of gifs in the background, and to download new fallback images defined through the dashboard.

Extract the URL from a link click. Add to application:openURL:options: in AppDelegate

Add this to - application:openURL:options: in your AppDelegate. If the URL was a Megacool URL, the event handler will be called with a MCLEventLinkClicked event.

Extract the URL from a link click. Add to application:openURL:sourceApplication: in AppDelegate if you support versions below iOS 9

Add this to - application:openURL:options: in your AppDelegate. If the URL was a Megacool URL, the event handler will be called with a MCLEventLinkClicked event.

Allow Megacool to handle a universal link opening the app, returning whether it was from a Megacool link or not. Add this to - application:continueUserActivity:restorationHandler: in your AppDelegate.

Start recording a GIF from a view.

This will keep a buffer of 50 frames (default). The frames are overwritten until stopRecording gets called.

Start customized GIF recording

This will keep a buffer of 50 frames (default). The frames are overwritten until stopRecording gets called.

Capture a single frame

Capture a single frame of the UIView to the buffer. The buffer size is 50 frames (default) and the oldest frames will be deleted if the method gets called more than 50 times. The total number of frames can be customized by setting the maxFrames property on the sharedMegacool instance. If you want a different strategy for handling too many frames, look at kMCLOverflowStrategyTimelapse.

Capture a customized frame for a GIF

Capture a single frame of the UIView to the buffer. The buffer size is 50 frames (default) and the oldest frames will be deleted if the method gets called more than 50 times. The total number of frames can be customized by setting the maxFrames property on the sharedMegacool instance.

If the overflow strategy is timelapse, we recommend setting maxFrames to a value where floor(maxFrames*4/3) is even, this maximizes the number of frames at any point in time present in the timalpse.

Pauses the current recording for resumption later.

The frames captured so far will be stored on disk and can be resumed later by calling startRecording / captureFrame with the same "recordingId".

Stop recording the UIView set in startRecording.

This method should be called after startRecording or captureFrame to mark the recording as completed. A completed recording can not have any more frames added to it, calling captureFrame or startRecording with the same recordingId as a completed recording will overwrite the old one.

Delete a recording.

Will remove any frames of the recording in memory and on disk. Both completed and incomplete recordings will take space on disk, thus particularly if you’re using keepCompletedRecordings=YES you might want to provide an interface to your users for removing recordings they don’t care about anymore to free up space for new recordings.

Log a significant event for highlightRecording

For highlight recording strategy only. This will make note of the time that a significant event occurs so that highlight recording can select the most interesting part of the gameplay

Log a the change in point value for highlightRecording

For highlight recording strategy only. This will make note of the time that a significant event occurs along with the point value associated with it so that highlight recording can select the most interesting part of the gameplay

Get the number of frames in the current recording

This method is used to know if frames exist in the current recording, before showing a preview or displaying a share button.

Get the number of frames from a specific recording

This method is used to know if frames exist in the current recording, before showing a preview or displaying a share button.

Wrapper for mcl_init_capture. Used by custom engines.

Wrapper for mcl_init_render_thread. Used by custom engines.

Wrapper for mcl_notify_render_complete. Used by custom engines.

Get a view that previews the default recording.

Call startAnimating on the returned MCLPreview to start the animation. Use getPreviewWithConfig to customize which recording to preview, or set where the view should appear. You can also set the frame on the returned view to position it.

Render preview of GIF with a given frame size that can be showed before sharing.

Call startAnimating on the returned MCLPreview to start the animation.

Get the data needed to build your own preview. This is a low-level interface intended for custom engines, you’re probably better of using the getPreview/getPreviewWithConfig methods.

Present the default share modal view in a view controller

Shows a native share modal view with supported sharing channels like SMS, Twitter, Facebook etc.

On some devices this might block for some time, to prevent user frustration we recommend showing a spinner and calling this method from a selector with [self performSelector:withObject:afterDelay:], using a delay of .1 (otherwise some devices won’t show the spinner at all before blocking). You should then stop and remove the spinner once this method returns. Example:

- (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];
}

Present the default share modal view in a view controller

Shows a native share modal view with supported sharing channels like SMS, Twitter, Facebook etc.

On some devices this might block for some time, to prevent user frustration we recommend showing a spinner and calling this method from a selector with [self performSelector:withObject:afterDelay:], using a delay of .1 (otherwise some devices won’t show the spinner at all before blocking). You should then stop and remove the spinner once this method returns. Example:

- (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] presentShareWithConfig:^(MCLShareConfig *config) {
       config.recordingId = @"level1";
   }];
   [self.spinner stopAnimating];
   [self.spinner removeFromSuperview];
}

Present the default share modal view in a view controller

Shows a native share modal view with supported sharing channels like SMS, Twitter, Facebook etc.

On some devices this might block for some time, to prevent user frustration we recommend showing a spinner and calling this method from a selector with [self performSelector:withObject:afterDelay:], using a delay of .1 (otherwise some devices won’t show the spinner at all before blocking). You should then stop and remove the spinner once this method returns. Example:

- (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] presentShareWithConfig:^(MCLShareConfig *config) {
       config.recordingId = @"level1";
   } inViewController:self];
   [self.spinner stopAnimating];
   [self.spinner removeFromSuperview];
}

Present Twitter share

This opens the Twitter app if it’s installed, with a predefined tweet consisting of the sharing text and link. The GIF is copied to the pasteboard so the user can paste it in the tweet. The user will get a notification that teaches how to paste it. If the Twitter app is not installed, a notification will tell the user to install it.

On some devices this might block for some time, to prevent user frustration we recommend showing a spinner and calling this method from a selector with [self performSelector:withObject:afterDelay:], using a delay of .1 (otherwise some devices won’t show the spinner at all before blocking). You should then stop and remove the spinner once this method returns. Example:

 - (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] presentShareToTwitter];
    [self.spinner stopAnimating];
    [self.spinner removeFromSuperview];
 }

Present Twitter share

This opens the Twitter app if it’s installed, with a predefined tweet consisting of the sharing text and link. The GIF is copied to the pasteboard so the user can paste it in the tweet. The user will get a notification that teaches how to paste it. If the Twitter app is not installed, a notification will tell the user to install it.

On some devices this might block for some time, to prevent user frustration we recommend showing a spinner and calling this method from a selector with [self performSelector:withObject:afterDelay:], using a delay of .1 (otherwise some devices won’t show the spinner at all before blocking). You should then stop and remove the spinner once this method returns. Example:

- (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] presentShareToTwitterWithConfig:^(MCLShareConfig *config) {
       config.recordingId = @"level1";
   }];
   [self.spinner stopAnimating];
   [self.spinner removeFromSuperview];
}

Present Messenger share view

Presents a Messenger share view where the user can compose a message that includes a link to your app and the recorded GIF.

On some devices this might block for some time, to prevent user frustration we recommend showing a spinner and calling this method from a selector with [self performSelector:withObject:afterDelay:], using a delay of .1 (otherwise some devices won’t show the spinner at all before blocking). You should then stop and remove the spinner once this method returns. Example:

- (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] presentShareToMessenger];
   [self.spinner stopAnimating];
   [self.spinner removeFromSuperview];
}

Present Messenger share view

Presents a Messenger share view where the user can compose a message that includes a link to your app and the recorded GIF.

On some devices this might block for some time, to prevent user frustration we recommend showing a spinner and calling this method from a selector with [self performSelector:withObject:afterDelay:], using a delay of .1 (otherwise some devices won’t show the spinner at all before blocking). You should then stop and remove the spinner once this method returns. Example:

- (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] presentShareToMessengerWithConfig:^(MCLShareConfig *config) {
       config.recordingId = @"level1";
   }];
   [self.spinner stopAnimating];
   [self.spinner removeFromSuperview];
}

Present a native iMessage share view

On some devices this might block for some time, to prevent user frustration we recommend showing a spinner and calling this method from a selector with [self performSelector:withObject:afterDelay:], using a delay of .1 (otherwise some devices won’t show the spinner at all before blocking). You should then stop and remove the spinner once this method returns. Example:

- (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] presentShareToMessages];
   [self.spinner stopAnimating];
   [self.spinner removeFromSuperview];
}

Present a native iMessage share view

On some devices this might block for some time, to prevent user frustration we recommend showing a spinner and calling this method from a selector with [self performSelector:withObject:afterDelay:], using a delay of .1 (otherwise some devices won’t show the spinner at all before blocking). You should then stop and remove the spinner once this method returns. Example:

- (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] presentShareToMessagesWithConfig:^(MCLShareConfig *config) {
       config.recordingId = @"level1";
   }];
   [self.spinner stopAnimating];
   [self.spinner removeFromSuperview];
}

Present a native iMessage share view

On some devices this might block for some time, to prevent user frustration we recommend showing a spinner and calling this method from a selector with [self performSelector:withObject:afterDelay:], using a delay of .1 (otherwise some devices won’t show the spinner at all before blocking). You should then stop and remove the spinner once this method returns. Example:

- (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] presentShareToMessagesWithConfig:^(MCLShareConfig *config) {
       config.recordingId = @"level1";
   } inViewController:self];
   [self.spinner stopAnimating];
   [self.spinner removeFromSuperview];
}

Present a native Mail share view

On some devices this might block for some time, to prevent user frustration we recommend showing a spinner and calling this method from a selector with [self performSelector:withObject:afterDelay:], using a delay of .1 (otherwise some devices won’t show the spinner at all before blocking). You should then stop and remove the spinner once this method returns. Example:

- (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] presentShareToMail];
   [self.spinner stopAnimating];
   [self.spinner removeFromSuperview];
}

Present a native Mail share view

On some devices this might block for some time, to prevent user frustration we recommend showing a spinner and calling this method from a selector with [self performSelector:withObject:afterDelay:], using a delay of .1 (otherwise some devices won’t show the spinner at all before blocking). You should then stop and remove the spinner once this method returns. Example:

- (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] presentShareToMailWithConfig:^(MCLShareConfig *config) {
       config.recordingId = @"level1";
   }];
   [self.spinner stopAnimating];
   [self.spinner removeFromSuperview];
}

Present a native Mail share view

On some devices this might block for some time, to prevent user frustration we recommend showing a spinner and calling this method from a selector with [self performSelector:withObject:afterDelay:], using a delay of .1 (otherwise some devices won’t show the spinner at all before blocking). You should then stop and remove the spinner once this method returns. Example:

- (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] presentShareToMailWithConfig:^(MCLShareConfig *config) {
       config.recordingId = @"level1";
   } inViewController:self];
   [self.spinner stopAnimating];
   [self.spinner removeFromSuperview];
}

Get the shares sent by the user.

The locally cached shares will be returned immediately and are useful for determining how many shares have been sent and when that was done. If the callback is non-nil we will query the backend for an updated status on the shares to see if anything has happened since last time.

Each element in the list returned will be a MCLShare (link to docs).

Get the shares sent by the user, with filtering.

Use this instead of -getShares: when you only want a subset of the shares, to keep network traffic to a minimum. The locally cached shares will be returned immediately and are useful for determining how many shares have been sent and when that was done. If the callback is non-nil we will query the backend for an updated status on the shares to see if anything has happened since last time.

Each element in the list returned will be a MCLShare (link to docs).

Delete local share objects

Local shares are also useful to show the users how many shares they’ve sent and what their statuses are. But at a certain time you might want to delete old ones.

Get the inviter id for this user/app.

The inviter id will be passed to the callback immediately if known, otherwise the callback will be called when we’ve received the inviter id from the backend, which happens on the first session, and will be stored locally after that.

Set capture method.

Note that kMCLCaptureMethodOpenGL requires some extra work, customizing this is primarily intended for custom engines for now.

Set sharing strategy.

What type of data should be prioritized when sharing to channels that support @em either GIF @em or links.

Set the text to be shared on different channels

Set numbers of frames per second to record.

Default is 10 frames / second. The GIF will be recorded with this frame rate.

Set numbers of frames per second to play.

Default is 20% more than the capture frame rate. The GIF will be exported with this frame rate.

Max number of frames in a recording.

Default is 50 frames. What happens when a recording grows above the maxFrames limit is determined by the overflow strategy, see the documentation for captureFrame or startRecording for details.

Percentage of highlight that should occur before maximum number of points is scored

Set a delay (in milliseconds) on the last frame in the animation.

Default is 1000 (1s). If set to 0 the last frame will have the same duration as the rest of the frames, ie. 1/playbackFrameRate.

Set a default custom overlay for the last frame in the animation.

This can be overridden on a per-recording basis by setting the lastFrameOverlay in the recording configuration instead. This can also be set as a URL if you have the image on disk with lastFrameOverlayUrl.

Set a default custom overlay for the last frame in the animation, by URL.

Same as lastFrameOverlay, but given as URL to a local filesystem path instead of UIImage. Can also be set per recording.

Assign the delegate for callbacks

Set the type of GIF color table to use. Default is kMCLGIFColorTableFixed

We recommend testing both options to see which looks best for your particular app.

The resulting GIF can only hold 256 different colors, this property determines how those colors are selected.

• kMCLGIFColorTableFixed: This is a fixed color table, which is very fast since no analysis is needed and performs well in the general case, but usually underperforms when representing nuanced differences and gradients.

• kMCLGIFColorTableAnalyzeFirst: The first frame is analyzed to generate a representative color table. This requires more CPU to create the GIF, but often yields better results when a GIF contains many shades of the same color. If new colors are introduced later in the GIF they will not be as accurately represented.

Set which Metal texture to capture from.

Whether to keep completed recordings around.

The default is NO, which means that all completed recordings will be deleted whenever a new recording is started with either captureFrame or startRecording. Setting this to YES means we will never delete a completed recording, which is what you want if you want to enable players to browse previous GIFs they’ve created. A completed recording will still be overwritten if a new recording is started with the same recordingId.

Turn on / off debug mode. In debug mode calls to the SDK are stored and can be submitted to the core developers using submitDebugDataWithMessage later.

Get whether debugging is currently enabled or not.

Disable a set of features

If something fails or is not desired on a class of devices, some features can be disabled remotely through the dashboard. To be able to test behavior when this is the case, or to always force a given feature to be disabled, you can call this function with a list of the features you want to disable.

Features disabled through this call will not be visible or configurable through the dashboard. A feature will be disabled if it’s disabled either through this call or remotely or both. This call will overwrite any effects of previous calls, thus calling disableFeatures:kMCLFeatureGifs followed by disableFeatures:kMCLFeatureAnalytics would leave only analytics disabled. Combine features with the bitwise OR operator | to disable multiple features, like disableFeatures:kMCLFeatureAnalytics|kMCLFeatureGifUpload.

The supported features you can disable is:

• GIFs: Disable all recording, frame capturing and subsequent creation of the GIF. Available as the constant kMCLFeatureGifs.
• GIF uploading: By default all GIFs created are uploaded to our servers, which is necessaryto be able to share GIFs to Facebook and Twitter, and for you to see them in the dashboard. This does have some networking overhead though, so if you’re very constrained in terms of bandwidth you can disable this. Include the constant kMCLFeatureGifUpload.
• Analytics: To be able to determine whether an install or an app open event came from a link we have to submit some events to our servers to be able to match the event to a link click detected by us. If you are very concerned about your user’s privacy or don’t want to incur the extra networking required, you can disable this feature. Note that users will not be credited for inviting friends if this feature is off. Include the constant kMCLFeatureAnalytics.

Submit debug data to the core developers along with a message explaining the expected outcome and what was observed instead.

Remember to set Megacool.debug = YES; on startup if you intend to use this call, otherwise the report will nots contain call traces and it’ll be harder to reproduce your issue.

Resets the device identity, enabling it to receive events with isFirstSession=YES again.

Use this if you’re testing the invite flow and you want to wipe previous data from the device. This will issue your device a new identity, which means it can receive recievedShareOpened events again with isFirstSession set to YES, and enabling you to click previous links sent by the same device, mitigating the need for multiple devices to test invites.

This method should be called before -startWithAppConfig:, otherwise the changes will not have any effect until the next session.