Unity Plugin Docs

Getting Started with the Swarm SDK on Android

Estimated Integration Time: 10 minutes

This guide provides step-by-step instructions for quickly integrating the Swarm SDK into an Android game or application. For convenience, the Swarm SDK is a library project. For more information about library projects click here.

In this guide we show you how to get started and setup Swarm in your app. After completing these steps, you'll be ready to add Leaderboards, Achievements, Cloud Data Saves, Virtual Stores and more!

If you need help or run into issues while integrating social features, please visit the Swarm Support Center.

Finally, if you're using the Unity Plugin, then please refer to the Unity Plugin Docs instead.

Prerequisites:

Install Eclipse
Install Android SDK
Install Android ADT (ver. 20.0.1 or newer)
Download Swarm SDK and unzip it

Step 1: Import and Link the Swarm Library

In Eclipse, click on File > Import > "Existing Projects into Workspace" (in the General folder)
Click Browse... and choose SwarmConnect/library as the root directory.
Right click on your app in the Package Explorer and choose "Properties".
On the left side, left click on "Android".
Under Library, click on "Add..." and choose SwarmConnect.
Click on "Apply" and then on "OK".
Do a Clean Build on SwarmConnect.
Do a Clean Build on your app.

Step 2: Set Manifest Merger Flag

Add this line to the bottom of your app's project.properties file:

manifestmerger.enabled=true

Step 3: Extend SwarmActivity

For Swarm to properly respond to requests, all activities in your app must extend SwarmActivity instead of Activity (SwarmActivity extends Activity). Note that the SwarmActivity class behaves the same as the Activity class, but it also does some work for you behind the scenes to manage interactions with Swarm.

public class MyActivity extends Activity {
public class MyActivity extends SwarmActivity {

[+] Important! Click here if you're using a library or framework that doesn't allow you to extend SwarmActivity (i.e. LibGDX, AndEngine, or the NDK).

Alternatives to extending SwarmActivity

Swarm needs to be notified as activities take the foreground (and leave the foreground). This enables Swarm to show notifications like "Achievement Unlocked" and "Item Purchased". Just add the following to each of your activities. It is very important to call Swarm.setActive(this) in both onCreate and onResume, and to call Swarm.setInactive(this) in onPause.

public void onCreate(Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    Swarm.setActive(this);
}

public void onResume() {
    super.onResume();
    Swarm.setActive(this);
}

public void onPause() {
    super.onPause();
    Swarm.setInactive(this);
}

Step 4: Setup your App in the Admin Panel

Go to the Admin Panel and click on "Create a New App".
Name the App and click on Submit.
Click on the App Details button at the top of the Admin Panel.
Write down the App ID and App Key (you'll need them soon).

Step 5: Initialize Swarm

You will need to initialize Swarm at every entry point into your app, typically this is in your main activity's onCreate() method. Add the following line of code in your main Acitiviy's onCreate() method and replace SWARM_APP_ID and "SWARM_APP_KEY" with your App ID and App Key from the Admin Panel.

Swarm.init(this, SWARM_APP_ID, "SWARM_APP_KEY");

[+] Click here to see more control and customization options.

(Optional) Listen for User Login and Logout

A SwarmLoginListener allows you to listen for various login and logout steps. By using a SwarmLoginListener you can decide what to do when the user starts the login process, the user intentionally cancels logging in, the user successfully logs in, and the user logs out. For example, a SwarmLoginListener can be useful for loading the user's cloud data when the user logs in.

First, create a SwarmLoginListener as shown below.

private SwarmLoginListener mySwarmLoginListener = new SwarmLoginListener() {

	// This method is called when the login process has started
	// (when a login dialog is displayed to the user).
	public void loginStarted() {
	}

	// This method is called if the user cancels the login process.
	public void loginCanceled() {
	}

	// This method is called when the user has successfully logged in.
	public void userLoggedIn(SwarmActiveUser user) {
	}

	// This method is called when the user logs out.
	public void userLoggedOut() {
	}

};

Finally, update the Swarm.init() call by adding your SwarmLoginListener as the 4th argument. It's that simple!

Swarm.init(this, SWARM_APP_ID, "SWARM_APP_KEY");
Swarm.init(this, SWARM_APP_ID, "SWARM_APP_KEY", mySwarmLoginListener);

(Optional) Add a Swarm Dashboard Entry Point

An entry point into Swarm's Dashboard can easily be attached to a button.

Button myButton = (Button)findViewById(R.id.my_swarm_button);
myButton.setOnClickListener(new OnClickListener() {
    public void onClick(View v) {
        Swarm.showDashboard();
    }
});

Many entry points into Swarm are available. The methods below will display the Login, Leaderboards, Achievements, and Store screens.

Swarm.showLogin();
Swarm.showLeaderboards();
Swarm.showAchievements();
Swarm.showStore();

(Optional) Launching on the Amazon AppStore

To make your game or app compatible with the Amazon Appstore (or another app store outside of Google Play), simply call the following method just before calling Swarm.init(...);

Swarm.enableAlternativeMarketCompatability();

Congratulations!

Your app now has the basic infrastructure required for Swarm! It's time to add some social features. You can add Leaderboards, Achievements, Cloud Data Saves, Virtual Stores and more! All features are completely modular and can be added in any order.

All features can be quickly integrated using Swarm's pre-built screens and toasts, but full APIs are available if you prefer to customize the features to match your game or app's look and feel.

Swarm Documentation API Reference