Shares and referrals

Share configuration

Shares can be customized by setting the default configuration, or overriding defaults on a per-share basis. Configuration given to an individual share will be merged with the global defaults.

Megacool megacool = [Megacool sharedMegacool];
megacool.defaultShareConfig.message = @"Come play with me!";
megacool.defaultShareConfig.fallbackImage =
    [UIImage imageNamed:@"shareFallback.gif"];
[megacool presentShareWithConfig:^(MCLShareConfig *config) {
    // Overrides the default "Come play with me!" set above for
    // this specific share
    config.message = @"Challenge me to a match!";
    config.url = [NSURL URLWithString:@"/challenge?player=ninja"];
]];

The example above will create a share link that looks like this: https://mgcl.co/<app-identifier>/challenge?player=ninja&_m=<referral-code>

When a receiver opens the app from the link, a MCLShare with the url given will be included in the MCLReceivedShareOpenedEvent event.

Handling shares and events

If you start Megacool with +[Megacool startWithAppConfig:andConfigBlock] you can specify a delegate in the config to receive events from the SDK as they happen. This could be a link being clicked, or someone installing the app from a referral.

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 SDK reference docs for the MCLDelegate and the MCLShare to see all fields and methods available.

This is an example of how to implement the event listener:

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [Megacool startWithAppConfig:@"undefined"
                andConfigBlock:^(MCLConfig *config) {
                    // Assuming self implements MCLDelegate
                    config.delegate = self;
                }
    ];
    return YES;
}
- (void)megacoolReceivedShareOpened:(MCLReceivedShareOpenedEvent *event) {
    // This device has received a share to the app and opened it
    NSLog(@"Got ReceivedShareOpenedEvent: %@", event);
    NSString *senderUserId = event.senderUserId;
    // Check if this is a first install
    if (event.isFirstSession) {
        // First install on this device
        NSLog(@"First install, invited by user id: %@", senderUserId);
    } else {
        // The app was already installed on this device
        NSLog(@"App opened, invited by user id: %@", senderUserId);
    }
}

Note: This event will not be triggered if you open the link from the same device that you shared the link from.

This is an example of how to implement the event listener:

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [Megacool startWithAppConfig:@"undefined"
                andConfigBlock:^(MCLConfig *config) {
                    // Assuming self implements MCLDelegate
                    config.delegate = self;
                }
    ];
    return YES;
}
- (void)megacoolSentShareOpened:(MCLSentShareOpenedEvent *event) {
    // The receiver of the share has opened it
    NSLog(@"Got SentShareOpenedEvent: %@", event);
    NSString *receiverUserId = event.receiverUserId;
    // Check if this is a first install
    if (event.isFirstSession) {
        // Receiver installed the app for the first time
        NSLog(@"Receiver installed the app, user id: %@", receiverUserId);
    } else {
        // The receiver had already installed the app
        NSLog(@"Receiver opened the app, user id: %@", receiverUserId);
    }
}

Note: This event will not be triggered if you open the link from the same device that you shared the link from. Also, the SDK only communicates with the backend occasionally, so this event might not be triggered immediately. You can force a check for new events by calling getShares:, as that will in addition to getting shares, check for new events.

- (void)refreshButton {
    // This causes a check for new events
    [[Megacool sharedMegacool] getShares:nil];
}

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.

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [Megacool startWithAppConfig:@"undefined"
                andConfigBlock:^(MCLConfig *config) {
                    // Assuming self implements MCLDelegate
                    config.delegate = self;
                }
    ];
    return YES;
}
- (void)megacoolLinkClicked:(MCLLinkClickedEvent *event) {
    // The app has been opened from a link. Send the user instantly
    // to the right location if the URL path exists.
    NSURL *url = event.url;
    NSLog(@"Clicked url: %@", url);
}

Testing that your referrals work

You can read about how to test your referrals here.

Share state

Call getShares: to get the updated state of a sent share. The locally cached shares will be returned immediately and are useful to determine the total number of shares. The callback, if given, will receive the up-to-date shares.

A share's MCLShareState describes how far it has come towards generating an install.

[[Megacool sharedMegacool] getShares:^(NSArray<MCLShare *> *shares) {
    for (MCLShare *share in shares) {
        if (share.state == MCLShareStateInstalled) {
            NSLog(@"Share sent on %@ created at least one install", share.createdAt);
        }
    }
}];

You can use the share state to display the number of friends that have been invited and what the state is:

The local share cache doesn't take up much space, but if you want to clean up a bit you can delete shares that match some given criteria. Here's an example that shows how to delete all shares that are older than 1 week:

[[Megacool sharedMegacool] deleteSharesMatchingFilterFromDevice:^BOOL(MCLShare *share) {
    NSTimeInterval shareAge = [[NSDate new] timeIntervalSinceDate:share.createdAt];
    return shareAge > 3600*24*7;
}];

Share directly to given apps

In addition to [[Megacool sharedMegacool] presentShare], you can also add shortcut buttons for sharing to specific apps. This reduces the numbers of steps needed to complete a share.

Messages

[[Megacool sharedMegacool] presentShareToMessages];

Mail

[[Megacool sharedMegacool] presentShareToMail];

These can also be further customized like described [above](#share-configuration).

Delegates after a share

If you need to dismiss a modal or similar when a share completes, the SDK has some events you can listen to to know when the sharing process ends.

- (BOOL)application:(UIApplication *)application
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    [Megacool startWithAppConfig:@"undefined"
        andConfigBlock:^(MCLMegacoolConfig *config) {
            // Assuming self implements the MCLDelegate protocol
            config.delegate = self;
    }];
}
- (void)megacoolDidCompleteShare {
    // Note that some apps the user can share to might report this even
    // though the share was actually dismissed
    NSLog(@"Share completed successfully");
}
- (void)megacoolDidDismissShareView {
    NSLog(@"Share was dismissed before completion");
}

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 sharedMegacool].defaultShareConfig.strategy = kMCLSharingStrategyMedia;