public class

Megacool

extends Object
java.lang.Object
   ↳ co.megacool.megacool.Megacool

Class Overview

The main interface to the Megacool SDK. Make sure you call start(Context, String, MegacoolConfig) early in the app lifecycle, preferably in your app's Application.

Summary

Nested Classes
enum Megacool.CaptureMethod Used to specify how captures should be performed. 
interface Megacool.OnUserIdReceivedListener Listener to get the user id for this device. 
interface Megacool.ShareCallback Listener to get the latest updated list of Share objects in getShares(ShareCallback)
interface Megacool.ShareFilter A filter to pass to getShares(ShareCallback, ShareFilter) to only get a selected types of shares back, like INSTALLED
Public Methods
void captureFrame(View view)
Capture a single frame of the provided View.
void captureFrame(View view, RecordingConfig config)
Capture a single frame of provided View with additional configuration.
void captureFrame(View view, RecordingConfig config, boolean forceAdd)
Capture a single frame of provided View with additional configuration.
void deleteRecording(String recordingId)
Delete a recording

Will remove any frames of the recording in memory and on disk.

void deleteShares(Megacool.ShareFilter filter)
Delete sent share objects that's not relevant anymore

Use the Megacool.ShareFilter to delete specific share objects or just pass true to delete all of them.

RecordingConfig getDefaultRecordingConfig()
Get the default recording config.
ShareConfig getDefaultShareConfig()
Get the default share config.
int getFrameRate(String recordingId)
Get the capture frame rate for a recording with the given id
static Megacool getInstance()
Get the Megacool singleton instance
int getNumberOfFrames(String recordingId)
Get the number of frames that exist for a recording with the given id
PreviewData getPreviewDataForRecording(String recordingId)
Get the raw data needed to build your own preview.
int getRecordingScore(String recordingId)
Get the total score for the given recording.
List<Share> getShares(Megacool.ShareCallback callback, Megacool.ShareFilter filter)
Get a filtered list of shares sent.
List<Share> getShares(Megacool.ShareCallback callback)
Get the 25 most recent shares.
static boolean handleDeepLink(Uri url)
Entry point for handling links with Megacool.
static void initRenderThread()
Low-level API for custom engines: Call this from the rendering thread to initialize the capture.
static void notifyRenderComplete()
Low-level API for custom engines: Call this after issuing all drawing commands for a frame on the rendering thread.
void pauseRecording()
Pauses the current recording for resumption later.
void registerScoreChange(int scoreDelta)
Call this when significant events in the gameplay occurs to mark it as interesting for the highlight algorithm when using HIGHLIGHT.
void registerScoreChange()
Call this when significant events in the gameplay occurs to mark it as interesting for the highlight algorithm when using HIGHLIGHT.
GifImageView renderPreviewOfGif()
Render preview of GIF that can be showed before sharing.
GifImageView renderPreviewOfGif(String recordingId)
Render preview of specific GIF recording that can be showed before sharing.
static void resetIdentity()
(For testing purposes) resets the device identity, restoring its ability to receive ReceivedShareOpenedEvent where isFirstSession() is true from receivedShareOpened(ReceivedShareOpenedEvent).
void setCaptureMethod(Megacool.CaptureMethod captureMethod, double scaleFactor)
Set how screen captures should be performed, using a custom scale factor.
void setCaptureMethod(Megacool.CaptureMethod captureMethod)
Set how screen captures should be performed, using the default scale factor.
static void setDebug(boolean enabled)
Enables writing debug info from Megacool to logcat and saving call traces to submit to the core developers.
void setDefaultRecordingConfig(RecordingConfig config)
Set the default recording config.
void setDefaultShareConfig(ShareConfig config)
Set the default share config.
void setGifColorTable(GifColorTable colorTable)
Set the color table to be used for the GIFs.
void setKeepCompletedRecordings(boolean keepCompletedRecordings)
Set whether completed recordings should be kept around for later, default is false.
void setOnUserIdReceivedListener(Megacool.OnUserIdReceivedListener onUserIdReceivedListener)
Use this to get the userId once it becomes available.
void share(Activity activity)
Share the recorded GIF with link and text through the default share view with channels like SMS, Twitter, Facebook etc.
void share(Activity activity, ShareConfig config)
Share the recorded GIF with link and text through the default share view with channels like SMS, Twitter, Facebook etc.
void shareScreenshot(Activity activity, View view)
Take a screenshot and share it immediately.
void shareScreenshot(Activity activity, View view, RecordingConfig recordingConfig, ShareConfig shareConfig)
Take a screenshot and share it immediately, with custom recording and/or share config.
void shareToMail(Activity activity)
Share the recorded GIF through a mail message

Opens an email composer view with a referral link and/or GIF, where the user can compose an email and send it to friends.

void shareToMail(Activity activity, ShareConfig config)
Share the recorded GIF through a mail message

Opens an email composer view with a referral link and/or GIF, where the user can compose an email and send it to friends.

void shareToMessages(Activity activity, ShareConfig config)
Share the recorded GIF through an SMS message

Opens the default SMS composer view with a referral link and/or GIF, where the user can compose a message and send it to friends.

void shareToMessages(Activity activity)
Share the recorded GIF through an SMS message

Opens the default SMS composer view with a referral link and/or GIF, where the user can compose a message and send it to friends.

static Megacool start(Context context, String appConfig)
Initialize the SDK in onCreate of your custom Application subclass.
static Megacool start(Context context, String appConfig, MegacoolConfig config)
Initialize the SDK singleton.
void startRecording(View view, RecordingConfig config)
Start a recording of a view with additional configuration.
void startRecording(View view)
Start a recording of a view.
void stopRecording()
Stop a recording of a view.
static void submitDebugData(String message)
Submit debug data to the core developers, along with a message explaining what you expected to happen and what happened instead.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public void captureFrame (View view)

Capture a single frame of the provided View.

The captured frame is added to a buffer (default size is 50) and oldest frames will be overwritten if the method gets called more than 50 times. The total number of frames can be set through maxFrames(int). To set additional configuration for capturing frames, use captureFrame(View, RecordingConfig).

This method only does anything on API level 18 and up.

Parameters
view The View you would like to record. Can be null if you're not using the VIEW capture method.

public void captureFrame (View view, RecordingConfig config)

Capture a single frame of provided View with additional configuration.

The captured frame is added to a buffer (default size is 50) and oldest frames will be overwritten if the method gets called more than 50 times. The total number of frames can be set through maxFrames(int).

Note that even though you pass a RecordingConfig for every call to this function, only the first one has any effect, you can't modify the configuration mid-recording. You have to give a different recording identifier or stop the old recording for configuration changes to take effect.

This method only does anything on API level 18 and up.

Parameters
view The View you would like to record
config Configure the recording with RecordingConfig

public void captureFrame (View view, RecordingConfig config, boolean forceAdd)

Capture a single frame of provided View with additional configuration.

The captured frame is added to a buffer (default size is 50) and oldest frames will be overwritten if the method gets called more than 50 times. The total number of frames can be set by calling maxFrames(int).

Note that even though you pass a RecordingConfig for every call to this function, only the first one has any effect, you can't modify the configuration mid-recording. You have to give a different recording identifier or stop the old recording for configuration changes to take effect.

This method only does anything on API level 18 and up.

Parameters
view The View you would like to record
config Configure the recording with RecordingConfig
forceAdd Override the overflow strategy's normal algorithm for whether a frame should be included in the recording or not. This is useful for crucial moments typically at the end of the recording, to ensure a final result or score is included. Note that this is only used when the recording is using the TIMELAPSE capture method.

public void deleteRecording (String recordingId)

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, so if you use multiple recordingIds it's smart to free up space for new recordings

This method only does anything on API level 18 and up.

Parameters
recordingId Delete the recording with this recordingId.

public void deleteShares (Megacool.ShareFilter filter)

Delete sent share objects that's not relevant anymore

Use the Megacool.ShareFilter to delete specific share objects or just pass true to delete all of them.

Parameters
filter A Megacool.ShareFilter to only delete relevant share objects.

public RecordingConfig getDefaultRecordingConfig ()

Get the default recording config.

Returns
  • the default recording config

public ShareConfig getDefaultShareConfig ()

Get the default share config.

Returns
  • the default share config

public int getFrameRate (String recordingId)

Get the capture frame rate for a recording with the given id

Parameters
recordingId The recordingId of the recording
Returns
  • The capture frame rate for a recording

public static Megacool getInstance ()

Get the Megacool singleton instance

Returns

public int getNumberOfFrames (String recordingId)

Get the number of frames that exist for a recording with the given id

Parameters
recordingId The recordingId of the recording, or null to get the count for the default recording
Returns
  • The current number of frames that exist in the recording, or -1 if the recording wasn't found

public PreviewData getPreviewDataForRecording (String recordingId)

Get the raw data needed to build your own preview. This is mostly useful for non-native Android apps that can't use renderPreviewOfGif().

This method only returns non-null values on API level 18 and up.

Parameters
recordingId The recordingId of the recording
Returns
  • preview data, or null if there were no frames in the given recording.

public int getRecordingScore (String recordingId)

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.

Parameters
recordingId The recording to fetch the score for. Fetches the default if null.
Returns
  • The score for the given recording, or -1 if the recording couldn't be found.

public List<Share> getShares (Megacool.ShareCallback callback, Megacool.ShareFilter filter)

Get a filtered list of shares sent.

Sent share objects are available so you can use their state to perform specific actions, like showing how many shares have been sent by a user and how many that led to INSTALLED. The locally cached shares will be returned immediately and are useful for determining how many shares have been sent. The server will be queried for an updated state of the shares, passing them to the callback if given. This is useful to get the latest ShareState for the shares.

Since this causes a network request this method also serves to check for new events for the user.

If the filter is null a default filter that returns the 25 most recent shares is used.

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.

Parameters
callback a callback to receive the updated shares
filter a Megacool.ShareFilter to select which shares should be updated
Returns
  • shares cached locally

public List<Share> getShares (Megacool.ShareCallback callback)

Get the 25 most recent shares.

Sent share objects are available so you can use their state to perform specific actions, like showing how many shares have been sent by a user and how many that led to INSTALLED. The locally cached shares will be returned immediately and are useful for determining how many shares have been sent. The server will be queried for an updated state of the shares, passing them to the callback if given. This is useful to get the latest ShareState for the shares.

Since this causes a network request this method also serves to check for new events for the user.

Parameters
callback a callback to receive the updated shares
Returns
  • shares cached locally

public static boolean handleDeepLink (Uri url)

Entry point for handling links with Megacool. Usually you don't have to call this manually, it's handled automatically if you've added the Megacool intent-filters to your main activity and the ReferralReceiver to your manifest as the documentation specifies. If for some reason you can't use those, get the link that opened your app in your own way and then call this method.

If the link is parsed successfully and is a Megacool link, a LinkClickedEvent event with the parsed url will be passed to your EventListener.

Ensure that start(Context, String, MegacoolConfig) is called before calling this method.

Parameters
url the url that opened your app.
Returns
  • true if the SDK was initialized and parsed the url successfully, otherwise false.

public static void initRenderThread ()

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 notifyRenderComplete().

public static void 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 initRenderThread() hasn't been called, thus you might want to call that during startup of the app to prevent any lag when recording starts.

public void pauseRecording ()

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(View) or captureFrame(View).

Note: If the app goes to the background, pauseRecording will automatically be called.

This method only does anything on API level 18 and up.

public void registerScoreChange (int scoreDelta)

Call this when significant events in the gameplay occurs to mark it as interesting for the highlight algorithm when using HIGHLIGHT. Use the scoreDelta to mark an event as more or less interesting compared to other events.

Parameters
scoreDelta the amount the score changed by

public void registerScoreChange ()

Call this when significant events in the gameplay occurs to mark it as interesting for the highlight algorithm when using HIGHLIGHT.

Equivalent to registerScoreChange(1).

public GifImageView renderPreviewOfGif ()

Render preview of GIF that can be showed before sharing.

Calling this method will automatically pause the recording. It assumes that id(String) hasn't been set, if you wish to show a preview of a specific recording, use renderPreviewOfGif(String) instead.

This method only returns non-null values on API level 18 and up.

Returns
  • An ImageView that can be positioned and scaled to fit the app, or null if something fails while loading the preview, or there are no frames in the recording to preview. When the GifImageView is no longer needed, it must be destroyed by calling destroy()

public GifImageView renderPreviewOfGif (String recordingId)

Render preview of specific GIF recording that can be showed before sharing.

Calling this method will automatically pause the recording.

This method only returns non-null values on API level 18 and up.

Parameters
recordingId The recordingId of the recording
Returns
  • An ImageView that can be positioned and scaled to fit the app, or null if something fails while loading the preview, or there are no frames in the recording to preview. When the GifImageView is no longer needed, it must be destroyed by calling destroy()

public static void resetIdentity ()

(For testing purposes) resets the device identity, restoring its ability to receive ReceivedShareOpenedEvent where isFirstSession() is true from receivedShareOpened(ReceivedShareOpenedEvent).

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 enables you to click previous links sent by the same device, mitigating the need for multiple devices to test invites. Note: This method should be called before start(Context, String, MegacoolConfig), otherwise the changes will not have any effect until the next app session.

public void setCaptureMethod (Megacool.CaptureMethod captureMethod, double scaleFactor)

Set how screen captures should be performed, using a custom scale factor. Call this as soon as possible after start(Context, String). 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 (this is required for Facebook previews). 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.

The default is probably fine, this is mostly useful for non-native apps.

public void setCaptureMethod (Megacool.CaptureMethod captureMethod)

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

public static void setDebug (boolean enabled)

Enables writing debug info from Megacool to logcat and saving call traces to submit to the core developers. Useful if you're not seeing the behavior you expected and want to help us figure out what is going wrong. Enable this before calling submitDebugData(String).

public void setDefaultRecordingConfig (RecordingConfig config)

Set the default recording config. This will be merged with the config given to startRecording(View, RecordingConfig) or captureFrame(View, RecordingConfig), if any.

Parameters
config the config to use, or null to revert to the defaults.

public void setDefaultShareConfig (ShareConfig config)

Set the default share config. This will be merged with the config given to share(Activity, ShareConfig), if any.

Parameters
config the config to use, or null to revert to the defaults.

public void setGifColorTable (GifColorTable colorTable)

Set the color table to be used for the GIFs.

Parameters
colorTable The color table to use for subsequent GIFs.
See Also

public void setKeepCompletedRecordings (boolean keepCompletedRecordings)

Set whether completed recordings should be kept around for later, default is false.

This acts as a regular disk cleanup and slight optimization if you don't intend to keep completed recordings around to be shared later. If you do, set this to true, and use deleteRecording(String) to delete recordings from disk that you don't need anymore. A completed recording will still be overwritten if a new recording is started with the same recordingId.

Parameters
keepCompletedRecordings whether to keep completed recordings on disk

public void setOnUserIdReceivedListener (Megacool.OnUserIdReceivedListener onUserIdReceivedListener)

Use this to get the userId once it becomes available. Note that the onUserIdReceived(String) method will be called on the same thread that this method is called on, and will be called immediately if the userId is already available.

Parameters
onUserIdReceivedListener a listener to receive the user id

public void share (Activity activity)

Share the recorded GIF with link and text through the default share view with channels like SMS, Twitter, Facebook etc.

This method should be called after a completed recording stopRecording()

Parameters
activity An activity used to launch the share modal

public void share (Activity activity, ShareConfig config)

Share the recorded GIF with link and text through the default share view with channels like SMS, Twitter, Facebook etc.

This method should be called after a completed recording stopRecording()

Parameters
activity An activity used to launch the share modal
config Configuration of the share by passing a ShareConfig object

public void shareScreenshot (Activity activity, View view)

Take a screenshot and share it immediately.

This is a helper around captureFrame(View) and share(Activity) when you only need to share a screenshot and not all the other bells and whistles for recordings.

This method is functionally equivalent to

 Megacool.getInstance().pauseRecording();
 String tempRecordingId = "random-unused-id";
 Megacool.getInstance().captureFrame(view, new RecordingConfig()
     .id(tempId)
     .maxFrames(1));
 Megacool.getInstance().share(activity, new ShareConfig()
     .recordingId(tempRecordingId)
     .modalTitle("Share screenshot"));
 Megacool.getInstance().deleteRecording(tempRecordingId);
 

Note that if this method is called while a recording is underway the screenshot is likely to be missing from the share. To stay on the safe side, leave a couple hundred ms between stopping a recording and sharing a screenshot.

Parameters
activity the activity to share from
view the view to capture, or
null
if not using VIEW

public void shareScreenshot (Activity activity, View view, RecordingConfig recordingConfig, ShareConfig shareConfig)

Take a screenshot and share it immediately, with custom recording and/or share config.

This is a helper around captureFrame(View) and share(Activity) when you only need to share a screenshot and not all the other bells and whistles for recordings.

This method is functionally equivalent to

 Megacool.getInstance().pauseRecording();
 String tempRecordingId = "random-unused-id";
 Megacool.getInstance().captureFrame(view, new RecordingConfig()
     .id(tempId)
     .maxFrames(1));
 Megacool.getInstance().share(activity, new ShareConfig()
     .recordingId(tempRecordingId)
     .modalTitle("Share screenshot"));
 Megacool.getInstance().deleteRecording(tempRecordingId);
 

Note that if this method is called while a recording is underway the screenshot is likely to be missing from the share. To stay on the safe side, leave a couple hundred ms between stopping a recording and sharing a screenshot.

Parameters
activity the activity to share from
view the view to capture, or
null
if not using VIEW
recordingConfig the recording config, or
null
. Most properties here doesn't apply to screenshots, but the last frame overlay does.
shareConfig the share config, or
null

public void shareToMail (Activity activity)

Share the recorded GIF through a mail message

Opens an email composer view with a referral link and/or GIF, where the user can compose an email and send it to friends.

public void shareToMail (Activity activity, ShareConfig config)

Share the recorded GIF through a mail message

Opens an email composer view with a referral link and/or GIF, where the user can compose an email and send it to friends.

Parameters
activity an Activity used to launch the share modal
config Configuration of the share by passing a ShareConfig object

public void shareToMessages (Activity activity, ShareConfig config)

Share the recorded GIF through an SMS message

Opens the default SMS composer view with a referral link and/or GIF, where the user can compose a message and send it to friends.

Parameters
activity an Activity used to launch the share modal
config Configuration of the share by passing a ShareConfig object

public void shareToMessages (Activity activity)

Share the recorded GIF through an SMS message

Opens the default SMS composer view with a referral link and/or GIF, where the user can compose a message and send it to friends.

public static Megacool start (Context context, String appConfig)

Initialize the SDK in onCreate of your custom Application subclass.

To register a listener for event callbacks like referrals, use start(Context, String, MegacoolConfig) instead.

Parameters
context The Context of the Application.
appConfig Your appConfig from the Megacool Dashboard as a String
Returns
  • A Megacool instance, or null if invalid appConfig is given

public static Megacool start (Context context, String appConfig, MegacoolConfig config)

Initialize the SDK singleton. Call this as early as possible in your app startup cycle, preferably in the onCreate of your Application subclass. This ensures that we detect link clicks as early as possible, enabling you to load the correct view immediately without first loading something else.

Parameters
context The Context of the Application.
appConfig The app config from your app's dashboard.
config Customization of core aspects of the SDK, like a listener for link clicks and referral events.
Returns
  • A Megacool singleton instance, or null if an invalid appConfig is given.

public void startRecording (View view, RecordingConfig config)

Start a recording of a view with additional configuration. Call stopRecording() when the recording should stop.

The recording keeps a buffer of frames (default is 50). The buffer size can be set with maxFrames(int). The oldest frames are overwritten until stopRecording() gets called.

This method only does anything on API level 18 and up.

Parameters
view The View you would like to record. Can be null if you're not using the VIEW capture method.
config Configure the recording with RecordingConfig

public void startRecording (View view)

Start a recording of a view. Call stopRecording() when the recording should stop.

The recording keeps a buffer of frames (default is 50). The buffer size can be set with maxFrames(int). The oldest frames are overwritten until stopRecording() gets called.

Parameters
view The View you would like to record. Can be null if you're not using the VIEW capture method.

public void stopRecording ()

Stop a recording of a view. Call this after startRecording(View) or multiple captureFrame(View).

This marks a recording as completed and it can't have any more frames added to it. Calling startRecording(View) or captureFrame(View) will overwrite the existing recording.

This method only does anything on API level 18 and up.

public static void submitDebugData (String message)

Submit debug data to the core developers, along with a message explaining what you expected to happen and what happened instead. Remember to call setDebug(boolean) ()} as early as possible in the session to capture as much debug data as possible.