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.getInstance();
megacool.getDefaultShareConfig().message("Come play with me!");
megacool.getDefaultShareConfig().fallbackImage(R.id.share_fallback);
megacool.share(context, new ShareConfig()
    // Overrides the default "Come play with me!" set above for
    // this specific share
    .message("Challenge me to a match!")
    .url(Uri.parse("/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 Share with the url given will be included in the ReceivedShareOpenedEvent event.

Handling shares and events

If you start Megacool with Megacool.start(Context, String, MegacoolConfig), you can specify an event listener in the config to receive a callback from the SDK whenever something happens. 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 EventListener and the Share to see all fields and methods available.

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

Megacool.start(this, "undefined", new MegacoolConfig()
    .eventListener(new EventListener() {
        @Override
        public void receivedShareOpened(@NonNull ReceivedShareOpenedEvent event) {
            // This device has received a share to the app and opened it
            Log.d(TAG, "Got ReceivedShareOpenedEvent: " + event);
            // Get the user id of the sender
            String senderUserId = event.getSenderUserId();
            if (event.isFirstSession()) {
                // First install on this device
                Log.d(TAG, "First install, invited by user id: " + senderUserId);
            } else {
                // The app was already installed on this device
                Log.d(TAG, "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:

Megacool.start(this, "undefined", new MegacoolConfig()
    .eventListener(new EventListener() {
        @Override
        public void sentShareOpened(@NonNull SentShareOpenedEvent event) {
            // The receiver of the share has opened it
            Log.d(TAG, "Got SentShareOpenedEvent: " + event);
            // Get the user id of the receiver
            String receiverUserId = event.getReceiverUserId();
            if (event.isFirstSession()) {
                // Receiver installed the app for the first time
                Log.d(TAG, "Receiver installed the app, user id: " + receiverUserId);
            } else {
                // The receiver had already installed the app
                Log.d(TAG, "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(ShareCallback), as that will in addition to getting shares, check for new events.

void refreshButton() {
    // This causes a check for new events
    Megacool.getInstance().getShares(null);
}

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.

Megacool.start(this, "undefined", new MegacoolConfig()
    .eventListener(new EventListener() {
        @Override
        public void linkClicked(@NonNull LinkClickedEvent event) {
            // The app has been opened from a link. Send the user instantly
            // to the right location if the URL path exists.
            Uri url = event.getUrl();
            Log.d(TAG, "Clicked url: " + url);
            // Assuming you have a way to challenge other players and that
            // urls are created like "/challenge?player=ninja" you can
            // implement links that take you straight to the challenge
            // like this
            if ("/challenge".equals(url.getPath()) {
                Intent next = new Intent(this, ChallengePlayerActivity.class);
                next.putExtra("CHALLENGED_PLAYER", url.getQueryParameter("player"));
                next.flags = Intent.FLAG_ACTIVITY_NEW_TASK;
                startActivity(next);
            }
        }
    })
);

Testing that your referrals work

You can read about how to test your referrals here.

Share state

Call getShares(ShareCallback) 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 ShareState describes how far it has come towards generating an install.

Megacool.getInstance().getShares(new Megacool.ShareCallback() {
    @Override
    public void shares(List<Share> shares) {
        for (Share share : shares) {
            if (share.getState() == ShareState.INSTALLED) {
                Log.d(TAG, "Share sent on " + share.getCreatedAt() + " 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.getInstance().deleteShares(new Megacool.ShareFilter() {
    @Override
    public boolean accept(Share share) {
        long shareAgeMs = new Date().getTime() - share.getCreatedAt().getTime();
        return shareAgeMs > 1000*3600*24*7;
    }
});

Share directly to given apps

In addition to Megacool.getInstance().share(), you can also add shortcut buttons for sharing to specific apps. This reduces the numbers of steps needed to complete a share.

Messages

Megacool.getInstance().shareToMessages();

Mail

Megacool.getInstance().shareToMail();

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.

Megacool.start(this, "undefined", new MegacoolConfig()
    .eventListener(new EventListener() {
        // Don't trust the outcome reported by these callbacks 100%, as most apps
        // the user can share to don't correctly report the outcome of the share
        @Override
        public void shareCompleted() {
            Log.d(TAG, "Share completed successfully");
        }
        @Override
        public void sharePossiblyCompleted() {
            Log.d(TAG, "Share might have completed successfully");
        }
        @Override
        public void shareDismissed() {
            Log.d(TAG, "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.getInstance().getDefaultShareConfig().strategy(SharingStrategy.MEDIA);