This tutorial will walk you through the steps of using the Ride Request Widget in your Android app. We will set up and configure the SDK, then walk through a quick integration and an advanced integration.

¶ Your Android Project

We can create a new Empty Activity project to demonstrate how to begin using the SDK. In Android Studio, choose Start a new Android Studio Project and when prompted to Add an Activity to Mobile, select Empty Activity and click Next.

In the next screen, set the Activity Name field to any name you want, leave everything else as the default and click Finish. You now have a boilerplate app with just one activity!

¶ Add the SDK to your project

The best way to integrate the SDK into your existing project is to use a dependency manager. The SDK can be added to Maven or Gradle based projects. The following sections will focus on the respective dependency manager you use within your project.

Using a dependency manager such as Maven or Gradle makes it easy to keep your app udpated with the latest version of the SDK.

¶ Gradle

The following steps assume that you have successfully set up a Gradle project. To learn about Gradle, please refer to the official user guide.

In your Gradle project, navigate to your build script (build.gradle) and open it. Now, identify the dependencies section in your file and add the SDK as an external module dependency:

dependencies {
    compile 'com.uber.sdk:rides-android:0.5.3'
}

Now, use the IDE of your choice or a CLI like Gradlew to fetch the SDK resources and build your project.

¶ Maven

The following steps assume that you have successfully set up a Maven project. To learn about Maven, please refer to the official documentation.

In your Maven project, navigate to the pom.xml file and open it. Now, identify the dependencies section in your file and add the SDK as a new dependency project:

<dependencies>
<dependency>
<groupId>com.uber.sdk</groupId>
<artifactId>rides-android</artifactId>
<version>0.5.3</version>
</dependency>
</dependencies>

Finally, use the IDE of your choice or the maven command line interface mvn to fetch the SDK resources and build your project.

¶ Configure the SDK

Congratulations, you’ve added the Uber Rides Android SDK into your project! Next, you have to configure the SDK. More specifically, you have to define your Uber app details obtained from the developer dashboard.

In your application, create a SessionConfiguration builder object. Ultimately, this object will be passed to to the UberSdk class to initialize a new client object with the correct configuration properties.

The configuration builder has several methods to define a variety of settings. To keep things simple, set them all for now (even though some features might use only a subset of them):

import com.uber.sdk.android.core.UberSdk;
import com.uber.sdk.core.auth.Scope;
import com.uber.sdk.rides.client.SessionConfiguration;
...
SessionConfiguration config = new SessionConfiguration.Builder()
    // mandatory
    .setClientId("<CLIENT_ID>")
    // required for enhanced button features
    .setServerToken("<TOKEN>")
    // required for implicit grant authentication
    .setRedirectUri("<REDIRECT_URI>")
    // optional: set sandbox as operating environment
    .setEnvironment(SessionConfiguration.Environment.SANDBOX)
    .build();

Finally, you can initialize the SDK with the config object:

UberSdk.initialize(config);

With that, you are all set to use the SDK!

¶ Location Services

Requesting location services permission from user can be done using Android’s ActivityCompat class. The Android SDK checks permission for Manifest.permission.ACCESS_FINE_LOCATION, which must be granted to be able to retrieve the user’s current location.

¶ Quick Integration

The Uber Rides SDK provides a simple way to add the Ride Request Widget in only a few lines of code via the RideRequestButton.

You can add RideRequestButton programmatically:

RideRequestButton rideRequestButton = new RideRequestButton(context);
layout.addView(rideRequestButton);
Activity activity = this; // If you're in a fragment you must get the containing Activity!
int requestCode = 1234;
rideRequestButton.setRequestBehavior(new RideRequestActivityBehavior(activity, requestCode));
// Optional, default behavior is to use current location for pickup
RideParameters rideParams = new RideParameters.Builder()
        .setProductId("a1111c8c-c720-46c3-8534-2fcdd730040d")
        .setPickupLocation(37.775304, -122.417522, "Uber HQ", "1455 Market Street, San Francisco")
        .setDropoffLocation(37.795079, -122.4397805, "Embarcadero", "One Embarcadero Center, San Francisco")
        .build();
rideRequestButton.setRideParameters(rideParams);

You can also add the button through XML:

<LinearLayout
   xmlns:android="http://schemas.android.com/apk/res/android"
   xmlns:uber="http://schemas.android.com/apk/res-auto"
   android:layout_width="match_parent"
   android:layout_height="match_parent">

   <com.uber.sdk.android.rides.RideRequestButton
      android:layout_width="wrap_content"
      android:layout_height="wrap_content"
      uber:ub__style="black"/>
</LinearLayout>

That’s it! When a user taps the button, a RideRequestActivity will be presented, containing a RideRequestView prefilled with the information provided from the RideParameters object. If they aren’t signed in, the Activity will display a login page and automatically continue to the Ride Request Widget once they sign in.

¶ Custom Integration

If you want to provide a more custom experience in your app, there are a few classes to familiarize yourself with. Read the sections below and you’ll be requesting rides in no time!

¶ Login

The Uber SDK allows for three login flows: Implicit Grant (local web view), Single Sign On with the Uber App, and Authorization Code Grant (requires a backend to catch the local web view redirect and complete OAuth).

To use Single Sign On, you must register a hash of your application’s signing certificate in the App Signature field under the Settings tab of the developer dashboard.

To get the hash of your signing certificate, run this command with the alias of your key and path to your keystore:

keytool -exportcert -alias <your_key_alias> -keystore <your_keystore_path> | openssl sha1 -binary | openssl base64

Before you can request any rides, you need to get an AccessToken. The Uber Rides SDK provides the LoginManager class for this task. Simply create a new instance and use its login method to present the login screen to the user.

LoginCallback loginCallback = new LoginCallback() {
  @Override
  public void onLoginCancel() {
      // User canceled login
  }

  @Override
  public void onLoginError(@NonNull AuthenticationError error) {
      // Error occurred during login
  }

  @Override
  public void onLoginSuccess(@NonNull AccessToken accessToken) {
      // Successful login!  The AccessToken will have already been saved.
  }
}
AccessTokenManager accessTokenManager = new AccessTokenManager(context);
LoginManager loginManager = new LoginManager(accessTokenManager, loginCallback);
loginManager.login(activity);

The only required scope for the Ride Request Widget is the RIDE_WIDGETS scope, but you can pass in any other (general) scopes that you’d like access to. The call to loginWithScopes() presents an activity with a WebView where the user logs into their Uber account, or creates an account, and authorizes the requested scopes. In your Activity#onActivityResult(), call LoginManager#onActivityResult():

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data){
    super.onActivityResult(requestCode, resultCode, data);
    loginManager.onActivityResult(activity, requestCode, resultCode, data);
}

The default behavior of calling LoginManager.login(activity) is to activate Single Sign On, and if that is unavailable, fallback to Implicit Grant if privileged scopes are not requested, otherwise redirect to the Play Store. If Authorization Code Grant is required, set LoginManager.setRedirectForAuthorizationCode(true) to prevent the redirect to the Play Store. Implicit Grant will allow access to all non-privileged scopes, where as the other two both grant access to privileged scopes. Read more about scopes.

¶ Login Errors

Upon a failure to login, an AuthenticationError will be provided in the LoginCallback. This enum provides a series of values that provide more information on the type of error.

¶ Custom Authorization / TokenManager

If your app allows users to authorize via your own customized logic, you will need to create an AccessToken manually and save it in shared preferences using the AccessTokenManager.

AccessTokenManager accessTokenManager = new AccessTokenManager(context);
Date expirationTime = 2592000;
List<Scope> scopes = Arrays.asList(Scope.RIDE_WIDGETS);
String token = "obtainedAccessToken";
String refreshToken = "obtainedRefreshToken";
String tokenType = "obtainedTokenType";
AccessToken accessToken = new AccessToken(expirationTime, scopes, token, refreshToken, tokenType);
accessTokenManager.setAccessToken(accessToken);

The AccessTokenManager can also be used to get an access token or delete it.

accessTokenManger.getAccessToken();
accessTokenManager.removeAccessToken();

To keep track of multiple users, create an AccessTokenManager for each AccessToken.

AccessTokenManager user1Manager = new AccessTokenManager(activity, "user1");
AccessTokenManager user2Manager = new AccessTokenManager(activity, "user2");
user1Manager.setAccessToken(accessToken);
user2Manager.setAccessToken(accessToken2);

¶ RideRequestView

The RideRequestView is like any other view you’d add to your app. Create a new instance in your XML layout or programmatically. You can optionally add custom RideParameters or a custom AccessTokenSession. When you’re ready to show the Ride Request View, just call load().

RideRequestView rideRequestView = new RideRequestView(context);

//Optionally set Session, will use default session from UberSDK otherwise
//rideRequestView.setSession(session);

rideRequestView.setRideParameters(rideParameters)
rideRequestView.setRideRequestViewCallback(new RideRequestViewErrorCallback() {
    @Override
    public void onErrorReceived(RideRequestViewError error) {
        switch (error) {
            // Handle errors
        }
    }
});
layout.addView(rideRequestView);
rideRequestView.load();

---

¶ Where to go from here

Now that your users are able to request rides using the widget you can work on a deeper integration using our API.