Customize
1. Shares and referrals
2. GIF customization
3. Save recordings
4. Testing referrals
5. Troubleshooting
1. Shares and referrals
1.1 Custom sharing text
Edit the default sharing text to make it more personal and customized for each place you use it.
Megacool.Instance.Share(new MegacoolShareConfig() { Message = "Try to beat my score!",});
1.2 Share config
If you want to customize a share, create a MegacoolShareConfig
object and pass this
as an argument to Share(MegacoolShareConfig config)
.
string urlString = "level5/battle?username=nbroby";Dictionary<string, string> data = new Dictionary<string, string>();data.Add ("welcomeText", "Nick has invited you!");Megacool.Instance.Share(new MegacoolShareConfig { Url = new Uri(urlString, UriKind.Relative), Data = data,});
The example above will create a share link that looks like this:
https://mgcl.co/appId/level5/battle?_m=12345678&username=nbroby
When a receiver opens the app from the link, a MegacoolShare
object containing the
data and url will be included in the ReceivedShareOpened
event.
1.3 Handling shares and events
You can specify listeners for receiving a MegacoolEvent
from the server. A MegacoolEvent
can contain a MegacoolShare
object.
You can implement event listeners to:
- reward your users for referring friends
- send users to a specific location in the app
- automatically make two users friends
Check out the full docs for MegacoolEvent and MegacoolShare to see all fields and methods available.
1.3.1 Receiver opens a shared link
This is an example of how to implement the event listener:
// Receiver's callback for when a share has been openedMegacool.OnReceivedShareOpened += (MegacoolEvent megacoolEvent) => { Debug.Log("Event ReceivedShareOpened"); // The user id of the sender string senderUserId = megacoolEvent.Data["senderUserId"]; // Check if this is a first install if (megacoolEvent.FirstSession) { // First install on this device Debug.Log("First install, invited by user id: " + senderUserId); } else { // The app is already installed on this device Debug.Log("App opened, invited by user id: " + senderUserId); } Debug.Log("Share data: " + megacoolEvent.Share.Data);};
1.3.2 Sender is notified about an opened link
This is an example of how to implement the event listener:
// Sender's callback for when a share has been openedMegacool.OnSentShareOpened += (MegacoolEvent megacoolEvent) => { Debug.Log("Event SentShareOpened"); // The user id of the receiver string receiverUserId = megacoolEvent.Data["receiverUserId"]; // Check if this share resulted in a first install if (megacoolEvent.FirstSession) { // Receiver installed the app for the first time Debug.Log("Receiver installed the app, user id: " + receiverUserId); } else { // The app was already installed Debug.Log("Receiver opened the app, user id: " + receiverUserId); }};
Note: The SDK occasionally communicates with the server, so this event is not triggered immediately.
To reward a user right after a new install has occurred, you can add a "refresh" button that calls
GetShares
. The GetShares
method is used for checking the status of sent
shares, but it also requests the server for new events.
void RefreshButton() { Megacool.Instance.GetShares(shares => {});}
1.3.3 Link clicked
You can improve the experience for existing users by sending them to the right location in your app immediately after they've opened the link. This is only for users that already have the app installed.
// The app has been opened from a link. Send the user instantly to// the right location if the URL path exists.Megacool.OnLinkClicked += (MegacoolEvent megacoolEvent) => { Debug.Log("Event LinkClicked"); Debug.Log("Url: " + megacoolEvent.Data["url"]); Debug.Log("Invited by: " + ((MegacoolReferralCode)megacoolEvent.Data["referralCode"]).UserId);};
1.4 Share state
Call GetShares
to get the latest State
of a sent share. The locally
cached shares will be returned immediately and are useful to determine the total number of shares.
If the function is non-null a request will be sent to the server to get the
latest State
update for each share.
States can be:
MegacoolShare.MegacoolShareState.Sent
MegacoolShare.MegacoolShareState.Clicked
MegacoolShare.MegacoolShareState.Opened
MegacoolShare.MegacoolShareState.Installed
Megacool.Instance.GetShares(shares => { for (int i = 0; i < shares.Count; i++) { if (shares[i].State == MegacoolShare.MegacoolShareState.Clicked){ Debug.Log("Share sent on " + shares[i].CreatedAt + " was clicked"); } }});
You can use the share state to display the number of friends that have been invited and what the state is:

To delete local shares that you don’t need updates from anymore, simply call
DeleteShares
, where filter
is a function with
MegacoolShare
as an argument. Based on State
, CreatedAt
,
UpdatedAt
etc. you can return true
to delete the share object or
false
to keep it. Make sure GetShares
has completed the request to the
server before calling this, otherwise the deleted shares will just be re-added.
Megacool.Instance.DeleteShares(share => { return share.State == MegacoolShare.MegacoolShareState.Installed;});
1.5 Share directly to given apps
In addition to Megacool.Instance.Share
, you can add custom share buttons for specific apps.
This reduces the numbers of steps needed to complete a share.
1.5.1 Messages
Megacool.Instance.ShareToMessages();
1.5.2 Mail
Megacool.Instance.ShareToMail();
It's possible to customize these by passing MegacoolShareConfig
as argument to the methods
above.
1.6 Delegates after a share
To know when the share view completes add this code:
Megacool.Instance.CompletedSharing += () => { Debug.Log("Did Complete Share");};Megacool.Instance.DismissedSharing += () => { Debug.Log("Did Dismiss Share");};Megacool.Instance.PossiblyCompletedSharing += () => { Debug.Log("Share was either completed or dismissed");};
PossiblyCompletedSharing
will only be called on Android, where in most cases it's impossible for us to tell whether the share actually completed or not.
1.7 Sharing strategies
Not all apps support sharing both a link and a GIF, and we have to choose which one to include. By default the SDK will prioritize links, to ensure referrals work, but if you only want to ensure the GIFs are spread as widely as possible you can customize this behavior:
Megacool.Instance.Share(new MegacoolShareConfig() { Strategy = MegacoolSharingStrategy.MEDIA,});
2. GIF customization
2.1 Types of recording
2.1.1 Time recording
Add the following line of code where you want to start a recording:
Megacool.Instance.StartRecording();
The recording will by default keep a buffer of the last 5 seconds. Old frames get overwritten by new frames. See Max Frames for editing the default setting.
To end a recording, add the following line of code:
Megacool.Instance.StopRecording();
2.1.2 Highlight recording
The highlight recording feature records the ‘most interesting’ part of your game--whether this is an awesome action sequence, or a hilarious ‘fail’. It does this by keeping track of the gameplay's intensity as determined by metrics specific to your game.
Whenever a critical event (such as scoring a point, landing a cool combo, failing in an epic way, etc.) occurs, call this function to make note of the event (and optionally, its intensity):
Megacool.Instance.RegisterScoreChange(); // without intensityMegacool.Instance.RegisterScoreChange(42); // with intensity of 42
For easy integration, we suggest ‘piggy-backing’ off your game’s current score system by calling this function whenever the player’s score increases, with the amount that it increases by. We equate ‘intensity’ with a change in point value, but you can also experiment with assigning various intensities to events with subjective ‘cool’ value.
Add the following line of code at the beginning of your game to start capturing your highlight!
Megacool.Instance.StartRecording (new MegacoolRecordingConfig { OverflowStrategy = MegacoolOverflowStrategy.HIGHLIGHT,});
2.1.3 Peak location
Different games have different paces: in one game, an awesome move might be followed immediately by bland downtime, while in another game, there might be some cool graphics or an interesting cutscene immediately afterwards. To let you adjust how much to include after the action dies down, try experimenting with the peakLocation parameter. This parameter is specific to highlight recording and controls where the ‘peak’ (or, maximum change in point value) of your highlight occurs. In the previous example, we would want the first game to have a late peak location so we don't record too much boring downtime, and the first game to have an early peak location so we make sure to record the cool after-graphics. The value of the peak location (between 0 and 1, inclusive), determines at what percentage through the recording the peak will be placed.
For example, in a recording with 10 frames, a peakLocation of 0.2 means that the peak will occur near the beginning around frame 2, and a peakLocation of 0.8 means that the peak will occur near the end around frame 8. The default peakLocation is 0.7. You can set the peak location by calling:
Megacool.Instance.StartRecording(new MegacoolRecordingConfig() { OverflowStrategy = MegacoolOverflowStrategy.HIGHLIGHT, PeakLocation = 0.5,});
2.1.4 Capture individual frames
Capture each frame of the recording, e.g. on each user tap:
Megacool.Instance.CaptureFrame();
By default max 50 frames will be captured. If it exceeds 50 frames, old frames are overwritten
until Megacool.Instance.StopRecording
gets called to reset it. Add the following line of code to stop
a recording:
Megacool.Instance.StopRecording();
2.1.5 Timelapse
Timelapse is identical to the normal captureFrame
, except timelapse has different behavior when
overflowing MaxFrames
. If it's about to overflow, it will delete every other frame
captured so far, and half the rate of capturing (thus only storing every second image on the first
overflow, every fourth image on the next, and so on).
Megacool.Instance.CaptureFrame(new MegacoolRecordingConfig { OverflowStrategy = MegacoolOverflowStrategy.TIMELAPSE,});
If you want to guarantee that a frame is added to the timelapse (like an end screen or final state
of the game), pass a ForceAdd = true
parameter to captureFrame
like this:
Megacool.Instance.CaptureFrame(null, true);
Important: Only pass this parameter once! Normally this function returns as soon as it has
spawned a thread to do the actual capture, but if you pass ForceAdd = true
it will
run synchronously (e.g. not return until it has actually stored the frame. This is because usually
this is called as the last step before a session ends and the GIF is created, thus we need the call
to complete before creating the GIF. This enables you to change visible elements on the screen after
this call completes and be sure that it's not going to be included in the GIF.
2.2 Rendering preview
This creates a rendered preview of the GIF that can be displayed to the user before sharing.
Drag the MegacoolPreviewCanvas Prefab to your scene
In the script where you want to control the preview, add a public field with type
MegacoolGifPreview
. This will expose themegacoolGifPreview
field in the inspector for the GameObject.public MegacoolGifPreview megacoolGifPreview;Drag the MegacoolGifPreview GameObject onto the open field in the inspector of the GameObject you use. This will attach an instance of the MegacoolGifPreview object to the public field.

You can now call StartPreview
and StopPreview
to display or hide the preview.
megacoolGifPreview.StartPreview();
megacoolGifPreview.StopPreview();
2.3 Recording frame rate
Set numbers of frames to record per second. Recommended range: 1 - 10. The default is 10:
Megacool.Instance.StartRecording(new MegacoolRecordingConfig() { FrameRate = 8;});
Note: This only applies to recordings made with Megacool.Instance.StartRecording
, not
Megacool.Instance.CaptureFrame
.
Frame rate examples (with Playback frame rate: 10):

Frame rate: 5

Frame rate: 10

Frame rate: 25
2.4 Playback frame rate
Set the number of frames per second when playing the GIF. The default is 12 frames / second. The GIF will be exported with this frame rate and it doesn't affect the recording frame rate. Setting this value higher than the frame rate causes the recording to be sped up, setting it lower means it'll be slowed down.
Megacool.Instance.StartRecording(new MegacoolRecordingConfig() { PlaybackFrameRate = 11,});

Playback frame rate: 5

Playback frame rate: 10

Playback frame rate: 25
2.5 Max frames
Max number of frames to record, default is 50 frames. Change the maximum amount of captured frames by setting:
Megacool.Instance.StartRecording(new MegacoolRecordingConfig() { MaxFrames = 25,});

Max frames: 25

Max frames: 50

Max frames: 100
2.6 Delay last frame
Set a delay (in milliseconds) for the last frame of the GIF. The default is 1 second to give a natural break before the GIF loops again.
Megacool.Instance.StartRecording(new MegacoolRecordingConfig() { LastFrameDelay = 2000,});


1000 ms delay
(default)
2000 ms delay
2.7 Last frame overlay
With last frame overlay you can add a transparent image on top of the last GIF frame.
+
=
Create a folder called StreamingAssets
if you don't have it already and add the overlay image to the folder. Then call:
Megacool.Instance.StartRecording(new MegacoolRecordingConfig() { LastFrameOverlay = "overlay.png",});
2.8 Color table
A gif consists of 256 colors and there are three different ways we can compute those colors, with slightly varying quality and performance tradeoffs. Default is dynamic.
2.8.1 Dynamic
The frames are analyzed before encoding, yielding a good balance between quality and speed. This is the default.
2.8.2 Analyze first
The frames are analyzed before encoding 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. This option is only available on iOS, on Android the dynamic color table will be used instead.
Go to Window -> Megacool -> Configuration -> GIF Color Table and select Gif Color Table Analyze First
.
It can also be set programmatically:
Megacool.Instance.GifColorTable = Megacool.GifColorTableType.GifColorTableAnalyzeFirst;
2.9 Recording customization
Our Unity SDK will by default record everything that happens on screen if it's capable of it,
otherwise it'll fall back to copying whatever is shown by the main camera. If you don't have a main
camera or want your recording to include or exclude certain elements, add the MegacoolManager
script to the camera you want to record from, and hide or include elements with that camera's
culling mask.
3. Save recordings
Being able to save and resume recordings is useful for combining multiple game sessions together. These recordings are stored to disk to be retrieved and potentially resumed later. This is a great case for turn-based games like Words with Friends where waiting for the other user to finish the round could take many hours, and still create a GIF of the whole game play.
3.1 Start and resume a recording
All completed recordings will by default be deleted whenever a new recording is started with either
Megacool.Instance.CaptureFrame
or Megacool.Instance.StartRecording
. To save a recording you can set
Megacool.Instance.KeepCompletedRecordings = true;
To save multiple recordings you can set a RecordingId
in the config
object at StartRecording(MegacoolRecordingConfig config)
or CaptureFrame(MegacoolFrameCaptureConfig config)
. The
RecordingId
can be anything you prefer, for instance a name of the current
level like "level3"
.
A recording with a given RecordingId
can be resumed until
Megacool.Instance.StopRecording
is called. After calling Megacool.Instance.StopRecording
you can either share
the recording or start a new one from scratch with the same RecordingId
.
//Save recording of level 3 to diskMegacool.Instance.KeepCompletedRecordings = true;Megacool.Instance.StartRecording(new MegacoolRecordingConfig() { RcordingId: "level3",});
3.2 Pause recording
When you want to pause a recording that can be continued later, you call
PauseRecording
.
Megacool.Instance.PauseRecording();
3.3 Delete recording
DeleteRecording
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
Megacool.Instance.KeepCompletedRecordings = true;
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.
Megacool.Instance.DeleteRecording("level3");
3.4 Show a GIF from a specific recording
To show a GIF from a specific recording:
Megacool.Instance.StartPreview("level3");
3.5 Share a GIF from a specific recording
To share a GIF from a specific recording you pass the RecordingId
as a parameter to
Share(MegacoolShareConfig config)
.
Megacool.Instance.Share(new MegacoolShareConfig() { RecordingId = "level3"});
Note: Megacool.Instance.Share
calls PauseRecording
automatically, so
if you haven't called Megacool.Instance.StopRecording
before next time you call
Megacool.Instance.StartRecording
, the recording will continue from where you paused.
4 Testing referrals
For this you need two devices. Let’s call them Sender and Receiver. If you have your app installed already, please delete it from both devices.
4.1 iOS
Sender | Receiver |
---|---|
Follow the Quickstart guide and build the app to this device. | |
Run the app and share a link to Receiver. | Open the link and press “Play now” to simulate that you’re going to download the app. |
Add Megacool.Instance.ResetIdentity before Megacool.Instance.Start .
This will reset the device identity, so it acts as a new device
every time the app starts. Remember to remove this after you’re done testing.
|
|
Build and run the app. Now this device will receive the
ReceivedShareOpened event with FirstSession :
true and generate a new install.
|
|
Press the home button and re-open the app to instantly receive the
SentShareOpened event, like shown in the
Quickstart guide.
|
4.2 Android
Sender | Receiver |
---|---|
Follow the Quickstart guide and build the app to this device. | |
Run the app and share a link to Receiver. | |
Add Megacool.Instance.ResetIdentity before Megacool.Instance.Start .
This will reset the device identity, so it acts as a new device
every time the app starts. Remember to remove this after you’re done testing.
|
|
Connect this device to your computer and run the following in the terminal, to
simulate a new Google Play install:
adb shell am broadcast -a "com.android.vending.INSTALL_REFERRER" --es referrer '?_m=REFERRAL_CODE' "YOUR_ANDROID_PACKAGE" .
Replace REFERRAL_CODE with the _m parameter value from your shared link.
|
|
Build and run the app. Now this device will receive the
ReceivedShareOpened event with FirstSession :
true and generate a new install.
|
|
Press the home button and re-open the app to instantly receive the
SentShareOpened event, like shown in the
Quickstart guide.
|
5. Troubleshooting
When I find myself in times of trouble
Mother Mary comes to me
Speaking words of wisdom:
"submit a detailed debug log"
— Paul McCartney
When things turn sour, and you're done running in circles screaming and shouting, you can swap the
SDK over in debug mode to let it capture detailed call traces of what's happening, and automatically
submit a debug report to us. Do this by calling Megacool.Debug = true
as early as possible in
the session, and when your problem has been reproduced (or you believe it is about to happen), call
Megacool.Instance.SubmitDebugData("halp!");
to share the issue with us. Please try to explain in the message
what you expected to happen, and what happened instead. If you follow this procedure it will be much
easier for us to reproduce the issue you're having and get it fixed ASAP.
We appreciate you taking the time to help us find the cause of the bugs, and we're very sorry that we didn't find them ourselves.
Using a custom engine and seeing problems with the capture? Read about how to use our low-level API to optimize the capture process.