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.

Initializes the SDK with a config block.

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.

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.

Get the currently active capture method.

Set how screen captures should be performed, using the default scale factor. Call this as soon as possible after start. Calling this more than once leads to undefined behavior.

Set how screen captures should be performed, using the default scale factor. Call this as soon as possible after start. Calling this more than once leads to undefined behavior.

The default scale factor is 0.5 for screens whose longest side is < 1500 in length, or 0.25 for anything larger. If the resulting dimensions are less than 200 for either width or height, then the scale factor is increased to ensure a minimum of 200 or more in both dimensions. By passing in a value for ScaleFactor, you override this behavior. It’s important to keep in mind that while a larger scale factor will produce encoded media with a higher resolution, it will make captures and encoding slower, and also increase the size of the encoded media, which will increase both disk and network usage. In any case, we will round up the scaled dimensions to be divisible by 16, as this is a requirement for many MP4 encoders.

Get the total score for the given recording.

By observing this value you can learn what scores are average and which are good in your game, and use this to only prompt the user to share if it was a high-scoring recording, or promote high-scoring recordings in the game or use it to set the share text.

The score will be 0 if the recording doesn’t use the highlight overflow strategy, or if registerScoreChange has never been called.

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 off using the getPreview/getPreviewWithConfig methods.

Present the default share modal from the top 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 from the top 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 from a given 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 from a given view controller.

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 from a given view controller.

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. A network request will query the backend for an updated status on the shares to see if anything has happened since last time, and passed to the callback if given.

By default this returns the most recent 25 shares, use -getShares:withFilter to customize which shares should be updated.

Calling this method will also trigger a check for any new MCLSentShareOpenedEvents for the user.

Get the shares sent by the user, with filtering.

Use this instead of -getShares: when you want a specific 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. A network request will query the backend for an updated status on the shares to see if anything has happened since last time, and passed to the callback if given.

Calling this method will also trigger a check for any new MCLSentShareOpenedEvents for the user.

If filter is nil the 25 most recent shares will be returned and updated. If you want to get an updated state for shares from the last week that haven’t yet generated an install you could pass a filter like this:

^BOOL(MCLShare *share) {
   return fabs([share.createdAt timeIntervalSinceNow]) < 60*60*24*7 && share.state != MCLShareStateInstalled;
}

Note that only 25 shares can be updated in a single HTTP request, requesting more than 25 shares to be updated will cause several network requests and increase the latency before the callback is called. Keep the share count below 25 to keep bandwidth usage low and the response quick.

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 the default share config. This will be merged with the config given to presentShareWithConfig:, if any.

Set to nil to reset.

The default recording config. This will be merged with the config given to startRecording:withConfig or captureFrame:withConfig, if any.

Note that the config is mutable, but changes made to the default config after a call to startRecording or captureFrame will have no effect until the next recording is started.

Set to nil to reset.

Assign the delegate for callbacks

Set the type of GIF color table to use. The default is kMCLGIFColorTableDynamic.

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

This only has any effect when sharing to apps where .gif gives a better experience than .mp4. Try sharing to email or messages to see the impact of this.

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.

Low-level API for custom engines: Call this from the rendering thread to initialize the capture.

Calling this is optional, but reduces the overhead of the first call to -[Megacool notifyRenderComplete].

Low-level API for custom engines: Call this after issuing all drawing commands for a frame on the rendering thread.

Note that the first call to this function have to do some more work to initialize the capture if {@link #initRenderThread()} hasn’t been called, thus you might want to call that during startup of the app to prevent any lag when recording starts.

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.