Shares and referrals

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.

let megacool = Megacool.shared()
megacool?.defaultShareConfig.message = "Come play with me!"
megacool?.defaultShareConfig.fallbackImage =
    UIImage(named: "shareFallback.gif")
megacool?.presentShare { config in
    // Overrides the default "Come play with me!" set above for
    // this specific share
    config.message = "Challenge me to a match!"
    config.url = URL(string: "/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.start(withAppConfig: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.

Receiver opens a shared link

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

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Megacool.start(withAppConfig: "undefined") { config in
        // Assuming self implements MCLDelegate
        config.delegate = self
    }
    return true
}
func megacoolReceivedShareOpened(_ event: MCLReceivedShareOpenedEvent) {
    // This device has received a share to the app and opened it
    NSLog("Got ReceivedShareOpenedEvent: (event)")
    let 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.

Sender is notified about an opened link

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

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Megacool.start(withAppConfig: "undefined") { config in
        // Assuming self implements MCLDelegate
        config.delegate = self
    }
    return true
}
func megacoolSentShareOpened(_ event: MCLSentShareOpenedEvent) {
    // The receiver of the share has opened it
    NSLog("Got SentShareOpenedEvent: (event)")
    let receiverUserId = event.receiverUserId
    // Check if this is a first install
    if (event.isFirstSession) {
        // Receiver installed the app for the first time
        NSLog("Receiver install 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.

func refreshButton () {
    // This causes a check for new events
    Megacool.shared()?.getShares(nil)
}

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.

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Megacool.start(withAppConfig: "undefined") { config in
        // Assuming self implements MCLDelegate
        config.delegate = self
    }
    return true
}
func megacoolLinkClicked(_ event: MCLLinkClickedEvent) {
    // The app has been opened from a link. Send the user instantly
    // to the right location if the URL path exists.
    let url = event.url
    NSLog("Clicked url: (url)")
}

Testing that your referrals work

You can read about how to test your referrals here.

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.shared()?.getShares { shares in
    for share in shares {
        if (share.state == .installed) {
            NSLog("Share sent on (share.createdAt) created at least one install")
        }
    }
}

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.shared()?.deleteSharesMatchingFilter { (share) -> Bool in
    let shareAge = Date().timeIntervalSince(share.createdAt)
    return shareAge > 3600*24*7
}

In addition to Megacool.shared()?.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.shared()?.presentShareToMessages()

Mail

Megacool.shared()?.presentShareToMail()

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

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.

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    Megacool.start(withAppConfig: "undefined") { config in
        // Assuming self implements MCLDelegate
        config.delegate = self
    }
    return true
}
func megacoolDidCompleteShare() {
    // Note that some apps the user can share to might report this even
    // though the share was actually dismissed
    NSLog("Share completed successfully")
}
func megacoolDidDismissShareView() {
    NSLog("Share was dismissed before completion")
}

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.shared()?.defaultShareConfig.strategy = .media

Shares and referrals

Share configuration

Handling shares and events

Receiver opens a shared link

Sender is notified about an opened link

Link clicked

Testing that your referrals work

Share state

Share directly to given apps

Messages

Mail

Delegates after a share

Sharing strategies