Swarm Documentation API Reference

Pro Tips

This guide provides awesome Pro Tips to make Swarm even more enjoyable.

Speed Up Initialization
To improve performance during initialization, call the preload function as soon as possible (i.e., during a splash screen or other asset loading screen)
preload(myActivity, APP_ID, "APP_KEY");
where myActivity is a reference to the current activity, APP_ID and APP_KEY are the integer App ID and string App Key for the app (shown in the app's App Details tab).

Create a More Inviting Experience
To create a more inviting experience, you may want to allow users to optionally use the social features you've added.

Setting this up is simple. Wait until your user taps on a button on your game's home screen and/or wait until your splash screen has finished before making a call to Swarm.init(...).

In the example below, a the user will reach the HomeScreen without seeing any Swarm content. On the HomeScreen there is a swarm button that logs the user in. Instead calling Swarm.init(...) in the HomeScreen's onCreate() method, call it when the user taps on the play button (and only if Swarm is not already initialized). If the user has already logged in once, this code snippit will also automatically login the user (without showing the Swarm login screen). Note that auto-login will also work if the call to Swarm.init includes a SwarmLoginListener as its 4th input parameter.
public class HomeScreen extends SwarmActivity {
    public void onCreate(Bundle savedInstanceState) {

        // If the user has logged in at least once before, then
        // automatically login the user without showing the home screen.
        if ( Swarm.isEnabled() ) {
            Swarm.init(myActivity.this, SWARM_APP_ID, SWARM_APP_KEY);

        ((Button)findViewById(R.id.button_swarm).setOnClickListener(new OnClickListener() {

            public void onClick(View v) {
                if (! Swarm.isInitialized() ) {
                    Swarm.init(myActivity.this, SWARM_APP_ID, SWARM_APP_KEY);
Make sure that Swarm.init(...) has been called before your app needs to use any Swarm features. Swarm's features (i.e., Leaderboards, Achievements, Virtual Store, Cloud Data, etc.) can't be used unless Swarm has been initialized.

You can also use this pro tip, combined with a SwarmLoginListener as the 4th parameter in Swarm.init(...), to show your own app's home screen and then cleverly login the user when they press a play button. The possibilities are endless!

Make Cloud Data Even Faster
Due to the way that Swarm caches data, Cloud Data performance can be improved by using fewer keys with larger data payloads (instead of more keys with smaller data payloads).

Use this:
Not this:

Handle Swarm's Notifications & Toasts Manually (or Disable Them All Together)
Swarm gives you the flexibility to handle its notifications and corresponding toasts. For example, by default Swarm displays a toast when an achievement is unlocked or a score is submitted to a leaderboard. In some cases it may be desireable to have your game or app perform some action in addition to the Swarm toast, perform some action instead of the Swarm toast, or you may wish to disable the default Swarm toast all together.

The following code snippit shows you how to manually handle Swarm's achievement and leaderboard notification toasts. Similar methods can be used to handle just about SwarmNotification (or child of the SwarmNotification class).

Swarm.setNotificationDelegate(new SwarmNotificationDelegate() {

    public boolean gotNotification(SwarmNotification notification) {

        if (notification != null) {

            // Check to see if the notification is an achievement notification
            if (notification instanceof NotificationAchievement) {

                // Get the notification's data so you can use it
                String message = notification.getMessage();
                String title = notification.getTitle();
                int iconId = notification.getIconId();

                // Display your own custom toast
                Context context = getApplicationContext();
                int duration = Toast.LENGTH_SHORT;

                Toast toast = Toast.makeText(context, message, duration);

                // Return true to tell Swarm you've consumed the event
                // and thus Swarm will not display the default toast.
                return true;

            } else if (notification instanceof NotificationLeaderboard) {

                // Leaderboard notifications can be handled the same way
                // as achievement notifications...

                return true;
            } else {

                return false;


        return false;

Have another cool idea?
Contact us through the Swarm Support Center and we'll try to make it happen!