Customize

1. Shares and referrals

Make the default sharing text personal and custom for each place you use it

Megacool.Instance.SharingText = "Try to beat my score!";

MegacoolShare is an object for everything related to a share. It contains a State of the share, CreatedAt, UpdatedAt, Data and an Url. With this, you can add your own data and a path and query which will be merged with the final link like this: 'https://mgcl.co/appId/level5/battle?_m=12345678&username=nbroby'.

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 share object can be passed as an argument to Megacool.Instance.Share as shown above. When the receiving user presses the link, the app will open and the share object will be received through a MegacoolEvent in start(Action<MegacoolEvent> eventHandler) which you can read more about in 1.2 below.

1.3 Tracking shares

In addition to customizing the link and adding data from the sender, you can fetch this information on the receiving side to e.g.:

reward your users for referring friends,
send users to a specific place in the app, and
automatically make two users friends.

You can specify listeners for receiving a MegacoolEvent from the server. A MegacoolEvent can contain a MegacoolShare object.

There are three main events to handle when a receiving user clicks a link:

When a receiving user clicks a link to either open or install your app, OnMegacoolEvents and corresponding listener will receive the MegacoolEvent from the server right after the app is opened. The MegacoolEvent.Type is ReceivedShareOpened. FirstSession is a boolean telling whether the app was opened for the first time (new install) or just opened. The MegacoolEvent.Share contains the MegacoolShare object that was sent. With the data from the MegacoolShare object you can reward the user and give a custom onboarding experience.

1.3.2 Link click

You can improve the experience for existing users by sending them to the right place in your app immediately after they've clicked the link through Universal Link. E.g. to a game session. This is only for users that have the app installed. A MegacoolEvent where MegacoolEvent.Type is LinkClicked will be triggered. The MegacoolEvent has a MegacoolEvent.Data with the Path, Query, ReferralCode and URL from the link. In this case, the MegacoolShare object is nil because it has to be fetched from the server which is handled in Received Share Opened above.

The sender gets a MegacoolEvent of the type SentShareOpened when the receiver has opened the app from the shared link. The MegacoolEvent contains FirstSession to indicate whether the app was installed or just opened. This can be used to reward the sender. In addition MegacoolEvent.Data contains the receiving user's id from receiverUserId. This can be used to add the receiving user as a friend.

1.3.4 Implementation

Replace the initializer code from Quickstart with the following:

void Start() {
    // OnMegacoolEvents
    // Recieves a list of all megacool events as they occur:
    // LinkClicked, RecievedShareOpened, SentShareOpened
    Megacool.OnMegacoolEvents += (List<MegacoolEvent> events) => {
        foreach (MegacoolEvent e in events) {
            Debug.Log(e.Type + " event recieved");
        }
    };
    /* THIS DEVICE */
    // ReceivedShareOpened
    // This device has received a share to the app, including a share object
    Megacool.OnReceivedShareOpened += (MegacoolEvent e) => {
        Debug.Log("Event ReceivedShareOpened");
        Debug.Log(e);
        string invitedById = e.Share.ReferralCode.InviteId;
        if (e.FirstSession) {
            //First session means it's a new install
            Debug.Log("WelcomeText " + e.Share.Data ["welcomeText"]);
            //Add your friend to the friends list - based on InviteId
            Debug.Log("New install for this device, invited by: " + invitedById);
        } else {
            //The app is already installed
            Debug.Log("WelcomeText " + e.Share.Data ["welcomeText"]);
            Debug.Log("Open app, invited by: " + invitedById);
        }
    };
    // LinkClicked
    // The app has been opened from a link click, send the user instantly to
    // the right scene if the URL path exists
    Megacool.OnLinkClicked += (MegacoolEvent e) => {
        Debug.Log("Event LinkClicked");
        Debug.Log("Url: " + e.Data["url"]);
        Debug.Log("Invited by: " + ((MegacoolReferralCode)e.Data["referralCode"]).InviteId);
    };
    // SentShareOpened
    // A Friend has received a share from your device
    Megacool.OnSentShareOpened += (MegacoolEvent e) => {
        Debug.Log("Event SentShareOpened");
        string sentInviteToId = e.Data["receiverUserId"];
        if (e.FirstSession) {
            //First session means your friend just installed the app
            Debug.Log("First session for friend with id: "+ sentInviteToId);
        } else {
            //The app was already installed and the friend opened it from your link
            Debug.Log("New session for friend with id: "+ sentInviteToId);
        }
    };
    Megacool.Instance.Start();
}

Note: Ensure you register the callbacks before calling Megacool.Instance.Start() like shown above to ensure you don't lose any events, as the callbacks might get called already during that call.

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-nil 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 show the user how many friends users have invited and what the state is:

To delete local shares 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. If you call this method around GetShares, make sure GetShares has completed the request to the server, otherwise the deleted shares will just be re-added.

Megacool.Instance.DeleteShares(share => {
    return share.State == MegacoolShare.MegacoolShareState.Installed;
});

Ready to integrate a breathtaking solution? Megacool makes it possible to get deeply integrated into the most popular services for a better user experience. Instead of showing the share modal view with a lot of options, it's possible to add your own buttons that share directly to the channels.

It's possible to customize the share channels below by passing a config as argument. More on that in the following sections.

We recommend to show buttons for the channels below and a general button that calls Megacool.Instance.Share using this icon .

1.5.1 Messenger

Megacool has integrated the Messenger API. To share to Messenger you simply create a button with a Messenger icon that calls this method instead of Megacool.Instance.Share:

Megacool.Instance.ShareToMessenger();

In addition you also have to configure XCode according to Facebook's Getting Started guide: Configure Xcode Project

There are two ways for a user to share a GIF to Messenger, either by selecting friend(s) or send it as a reply to a previous conversation. Sending as a reply to a previous conversation requires that the user has opened your app from a conversation in Messenger.

Note: Sharing directly to Messenger doesn't support only sharing a URL. You have to provide a GIF and a fallback image, in case the GIF fails, or just a fallback image. Go to Fallback image to learn how to add a fallback image.

Note 2: When your app is installed from a direct Messenger share, the receiver will never get a Received share opened event. Hence you shouldn't use this for rewarded referrals. Opening shares with your app already installed works as expected.

1.5.2 Twitter

The native share feature to Twitter has a tiny issue. It converts GIFs to JPG. For users running <iOS11 we are solving this with the following function:

Megacool.Instance.ShareToTwitter();

Note: The first time a user choose Twitter, a prompt will ask to get access to their Twitter account.

1.5.3 iMessage

Sharing directly to iMessage gives a better user experience.

Megacool.Instance.ShareToMessages();

1.5.4 Mail

Sharing directly to Mail gives a better user experience.

Megacool.Instance.ShareToMail();

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.

2. GIF customization

2.1 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 the megacoolGifPreview 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.2 Recording frame rate

Set numbers of frames to record per second. Recommended range: 1 - 10. The default is 10:

Megacool.Instance.FrameRate = 5;

Set the frame rate right before calling Megacool.Instance.StartRecording.
NB: This only applies to recordings made with Megacool.Instance.StartRecording, not Megacool.Instance.CaptureFrame.

Frame rate examples (with Playback frame rate: 10):

2.3 Playback frame rate

Set the number of frames per second when playing the GIF. The default is 10 frames / second. The GIF will be exported with this frame rate and it doesn't affect the recording frame rate.

Megacool.Instance.PlaybackFrameRate = 5;

Make sure to call setPlaybackFrameRate before Megacool.Instance.Share when sharing the GIF.

2.4 Max frames

Max number of frames to record, default is 50 frames. Change the maximum amount of captured frames by setting:

Megacool.Instance.MaxFrames = 25;

2.5 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.LastFrameDelay = 2000;

2.6 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.setDefaultLastFrameOverlay("overlay.png");

Note 1: Since the GIF color space is only 256 colors, additional colors in the overlay image might interfere with the colors in the rest of the GIF. If using the fixed color table this will not make any difference, but with dynamic or analyze first color tables (see color table options) adding many new colors in the overlay might take up space for colors that would have otherwise helped improve the rest of the recording.

Note 2: On some channels GIFs may get cropped depending on the aspect ratio. To be on the safe side, make sure to place the text within the visible preview area on different channels with the following aspect ratio:

(1:1.4) Facebook, iMessage
(1:1.1) Twitter

2.7 Fallback image

Fallback image let's you share a predefined image in cases where you don't want a recording or if a recording has failed. The fallback image can be JPG, PNG or even a GIF!

Create a folder called StreamingAssets if you don't have it already and add the fallback image to the folder. Include the parameter FallbackImage when calling Share:

Megacool.Instance.Share(new MegacoolShareConfig {
    FallbackImage = "fallbackImage.png"
});

When choosing your image please keep in mind that there's a size limit for each social media platform, so use a reasonable size. E.g. Twitter has a 3MB limit for uploading an image.

Note: The image will not be uploaded on the following platforms because they only support sharing links:

Facebook
Facebook Messenger

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

2.9 Timelapse

Identical to the normal captureFrame, but 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 MegacoolFrameCaptureConfig {
    OverflowStrategy = MegacoolOverflowStrategy.TIMELAPSE
});

Timelapse

2.9.1 Force add

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 in config like this:

Megacool.Instance.CaptureFrame(new MegacoolFrameCaptureConfig {
    OverflowStrategy = MegacoolOverflowStrategy.TIMELAPSE,
    ForceAdd = 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 then 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.10 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.10.1 Dynamic

The frames are analyzed before encoding, yielding a good balance between quality and speed. This is the default.

2.10.2 Fixed

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.

Go to Megacool -> Configuration -> GIF Color Table and select Gif Color Table Fixed. Alternatively you can set it programmatically:

Megacool.Instance.GifColorTable = Megacool.GifColorTableType.GifColorTableFixed;

2.10.3 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 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.11 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.PeakLocation = 0.7;

3. Save recordings

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 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 disk
Megacool.Instance.KeepCompletedRecordings = true;
Megacool.Instance.StartRecording(new MegacoolRecordingConfig(
    recordingId: "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");

To share a GIF from a specific recording you pass the RecordingId as a parameter to Share(ShareConfig 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

4.1 Reset device identity

If you are testing the invite/sharing process local on your devices it would be great to reset them so they act as new devices. To reset the device identity for the Megacool SDK you simply call ResetIdentity as the first thing when your app starts, before start(Action<MegacoolEvent> eventHandler). Also clear all cookies in Safari as this is used to identify the device from the link click.

Megacool.Instance.ResetIdentity();

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.

Customize

1. Shares and referrals

2. GIF customization

3. Save recordings

4. Testing

5. Troubleshooting

1. Shares and referrals

1.1 Custom sharing text

1.2 Share object

1.3 Tracking shares

1.3.1 Received share opened

1.3.2 Link click

1.3.3 Sent share opened

1.3.4 Implementation

1.4 Share state

1.5 Share directly to channels

1.5.1 Messenger

1.5.2 Twitter

1.5.3 iMessage

1.5.4 Mail

1.6 Delegates after a share

2. GIF customization

2.1 Rendering preview

2.2 Recording frame rate

2.3 Playback frame rate

2.4 Max frames

2.5 Delay last frame

2.6 Last frame overlay

2.7 Fallback image

2.8 Recording customization

2.9 Timelapse

2.9.1 Force add

2.10 Color table

2.10.1 Dynamic

2.10.2 Fixed

2.10.3 Analyze first

2.11 Peak Location

3. Save recordings

3.1 Start and resume a recording

3.2 Pause recording

3.3 Delete recording

3.4 Show a GIF from a specific recording

3.5 Share a GIF from a specific recording

4. Testing

4.1 Reset device identity

5. Troubleshooting