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.

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.

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

func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
Megacool.start(withAppConfig: "YOUR_APP_CONFIG") { 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.

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

func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
Megacool.start(withAppConfig: "YOUR_APP_CONFIG") { 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)
}

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: "YOUR_APP_CONFIG") { 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.


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

Share directly to given apps

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.


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.

func application(_ application: UIApplication,
didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
Megacool.start(withAppConfig: "YOUR_APP_CONFIG") { 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")
}

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