- Android Studio 2.1.2 or higher
- Min Android SDK 18
- GooglePlayServices 9.0.2 on device
- Firebase account
Before continueing with the installation of the Rover SDK, please make sure you have setup you project and Android app in the Firebase Console.
The easiest way to get Rover into your Android project is to use the JCenter Maven repository. Just add the following line to the dependencies
section of your module's build.gradle
file:
compile 'io.rover.library:rover:0.3.1'
// COMING SOON
The Rover SDK MUST be initialized inside the Application base class onCreate
method. If your Android application doesn't already have an Application base class, follow these instructions to create one.
Add the following snippet to your Application's onCreate
method:
RoverConfig config = new RoverConfig.Builder()
.setApplicationToken("YOUR APPLICATION TOKEN HERE")
.build();
Rover.setup(this, config);
Call the startMonitoring()
method to begin monitoring for beacons and geofences. You may choose to do this step in any Activity of your choice.
IMPORTANT As of the Marshmallow release, the Android OS requries this to be wrapped in a permission check block. An example of a backwards compatible way to do this is shown below:
public class MainActivity extends AppCompatActivity {
public void startRoverMonitoring() {
if (Build.VERSION.SDK_INT >= 23) {
// Marshmallow+
if (ContextCompat.checkSelfPermission(getApplicationContext(), Manifest.permission.ACCESS_COARSE_LOCATION) != PackageManager.PERMISSION_GRANTED) {
requestPermissions(new String[]{Manifest.permission.ACCESS_FINE_LOCATION}, 0);
} else {
Rover.startMonitoring();
}
} else {
// Pre-Marshmallow
Rover.startMonitoring();
}
}
@Override
public void onRequestPermissionsResult(int requestCode, String[] permissions, int[] grantResults) {
if (requestCode == 0) {
if (grantResults[0] == PackageManager.PERMISSION_GRANTED) {
Rover.startMonitoring();
}
} else {
super.onRequestPermissionsResult(requestCode, permissions, grantResults);
}
}
}
Rover uses the observer pattern to notify the developer of proximity events. The Rover.addObserver();
method accepts any object implementing one or more of the RoverObservers.
Here's an example of an Activity
that adds itself as an observer and implements the MessageDeliveryObserver
interface.
public class MyActivity extends AppCompatActivity implements RoverObserver.MessageDeliveryObserver {
@Override
protected void onCreate(bundle savedInstanceState) {
super.onCreate(savedInstanceState);
Rover.addObserver(this);
}
@Override
protected void onDestroy() {
super.onDestroy();
Rover.removeObserver(this);
}
@Override
public void onMessageReceived(Message message) {
Log.i("RoverMessage", "Received message: " + message.getText());
}
}
IMPORTANT Notice that the example removes itself as an observer in the onDestory
method. This is required in order for the class to properly deallocate itself. Any call to Rover.addObserver();
must be balanced with a corresponding call to Rover.removeObserver();
.
// Coming soon
Using the Rover Messages App you can create messages that are delivered to your users when a proximity event is triggered or on a specific date and time. You can attach push notifications to your messages that will be delivered along with your messages. Additionally you can attach content to your messages. The content can be a landing page authored in the Rover Messages App or it can simply link to a website. A message can also trigger functionality within your app through a deep link and can have custom data attached.
In order to have notification and messages working, Rover needs your FCM server key. Use this guide to upload your configure Rover with your FCM setup.
If you like fine-grained control over notifications, you must register a NotificationProvider during initialization.
RoverConfig config = new RoverConfig.Builder()
.setApplicationToken("YOUR APPLICATION TOKEN HERE")
.setNotificationProvider(new NotificationProvider() {
...
})
.build();
Rover.setup(this, config);
Check the Notification Provider file for more documentation on methods to customize behavior.
Most applications provide means for users to recall messages. You can use the onMessageReceived(Message message)
callback on a MessageDeliveryObserver
to map and add Rover messages to your application's inbox as they are delivered. You may also rely solely on Rover for a simple implementation of such inbox if your application doesn't already have one:
Rover.reloadInbox(new Rover.OnInboxReloadListener() {
public void onSuccess(List<Message> messages) {
// Add to your adapter
}
public void onFailure() {}
});
Note that the reloadInbox
method will only return messages that have been marked to be saved in the Rover Messages app.
See the MessageFragment in the example app for a quick implementation.
If the message contains a landing page you probably want to present an activity for it. The getLandingPage()
method of a Message
object is of type Screen
. You can launch the ScreenActivity
using an Intent which has the Screen
object in its extras under the key ScreenActivity.INTENT_EXTRA_SCREEN
.
Intent intent = new Intent(this, ScreenActivity.class);
intent.putExtra(ScreenActivity.INTENT_EXTRA_SCREEN, message.getLandingPage());
startActivity(intent);