Pathshare is a realtime location sharing platform. For more information please visit the Pathshare Developer Page.

• Requirements
• Installation
• Basic Usage
  • Initialize Pathshare
  • Save Username
  • Create Session
  • Join Session
  • Invite Customer
  • Leave Session
  • Find Session

PathshareSDK for Android supports Android 5.x, 6.x, 7.x, 8.x, 9.x, 10.x, 11.x, 12.x and 13.x.

The installation of the PathshareSDK is simple. Download the latest pathshare-sdk-android-[version].zip from Releases, unzip and copy the PathshareSDK folder into the root of your project.

Next, reference the PathareSDK folder in your application build.gradle file:

repositories {
    maven { url "file://$projectDir/../PathshareSDK" }
}

dependencies {
    ...
    compile 'ch.freshbits.pathshare.sdk:pathshare-sdk:2.3.3'
}

In order to initialize the PathshareSDK, create a file named pathshare.xml inside the res/value folder and add your account token:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="pathshare_account_token">your Pathshare account token</string>
</resources>

Next, add the following to the onCreate method of your Application class:

public class ExampleApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();

        Pathshare.initialize(this, getString(R.string.pathshare_account_token), TrackingMode.SMART);
    }
}

class ExampleApplication: Application() {

    override fun onCreate() {
        super.onCreate()

        Pathshare.initialize(this, getString(R.string.pathshare_account_token), TrackingMode.SMART)
    }
}

Optionally, you can specify a tracking mode to configure the behavior of the location tracker. The following tracking modes are available:

Before creating a session, you need to save a user:

Pathshare.client().saveUser("Candice", "[email protected]", "+12345678901", UserType.DRIVER, getResources().getDrawable(R.drawable.face, null), new ResponseListener() {
    @Override
    public void onSuccess() {
        // ...
    }

    @Override
    public void onError(@NonNull Throwable throwable) {
        // ...
    }
});

Pathshare.client().saveUser("SDK User Android", "[email protected]", "+12345678901", UserType.DRIVER, resources.getDrawable(R.drawable.face, null), object: ResponseListener {
    override fun onSuccess() {
        // ...
    }

    override fun onError(throwable: Throwable) {
        // ...
    }
})

The email address can be null.

Use the same method Pathshare.client().saveUser() to create or update the user.

There are different types of users for specific industries:

To create a session, use the session builder:

session = new Session.Builder()
    .setExpirationDate(expirationDate)
    .setName("Shopping")
    .build();

session = Session.Builder()
    .setExpirationDate(expirationDate)
    .setName("Shopping")
    .build()

A session needs an expiration date and a name. You can create multiple sessions at the same time, the SDK will manage them for you.

Make sure to save the session after building:

session.save(new ResponseListener() { ... });

session.getIdentifier() // => 3fd919fe824d8e7b78e2c11c1570a6f168d2c...
session.isExpired() // => false
session.getURL() // => https://pathsha.re/6d39d5

session.save(object: ResponseListener { ... })

session.identifier // => 3fd919fe824d8e7b78e2c11c1570a6f168d2c...
session.isExpired // => false
session.url // => https://pathsha.re/6d39d5

In order to react to the expiration of the session, add an ExpirationListener:

session = new Session.Builder()
    // ...
    .setExpirationListener(new SessionExpirationListener() {
        @Override
        public void onExpiration() {
            // ...
        }
    })
    .build();

session = Session.Builder()
    // ...
    .setSessionExpirationListener { // ... }
    .build()

Optionally, you can add a destination to the session. Sessions with destination will show the estimated time of arrival (ETA) for each user. The destination identifier is used to group sessions by destination.

Destination destination = new Destination.Builder()
    .setIdentifier("W2342")
    .setLatitude(47.378178)
    .setLongitude(8.539256)
    .build();

session = new Session.Builder()
    // ...
    .setDestination(destination)
    .build();

val destination = Destination.Builder()
    .setIdentifier("W2342")
    .setLatitude(47.378178)
    .setLongitude(8.539256)
    .build()

session = Session.Builder()
    // ...
    .setDestination(destination)
    .build()

To join the session you created, call the joinUser() method on the session object:

session.join(new ResponseListener() { ... });

session.isUserJoined() // => true

session.join(object: ResponseListener { ... })

session.isUserJoined // => true

This call will add your Pathshare user to the session and you will be able to see his location on a map in realtime in the Pathshare Professional web interface.

To invite a customer to the session, call the inviteUser() method on the session object:

session.inviteUser("Customer", UserType.CLIENT, "[email protected]", "+12345678901", new InvitationResponseListener() {
    @Override
    public void onSuccess(URL url) {
        // ...
        Log.d("URL", url.toString()); // => https://m.pathsha.re/12s83a
    }

    public void onError(@NonNull Throwable throwable) {
        // ...
    }
});

session.inviteUser("Customer", UserType.CLIENT, "[email protected]", "+12345678901", object: InvitationResponseListener {
    override fun onSuccess(url: URL?) {
        // ...
        Log.d("URL", url.toString()) // => https://m.pathsha.re/12s83a
    }

    override fun onError(throwable: Throwable) {
        // ...
    }
})

This call will create a customer user and return an invitation URL that can be sent to the customer using your preffered channel. The customer will then see the driver's location in realtime as well as the ETA in a white-labeled view with your corporate identity.

The customer will be able to enjoy the full realtime experience in the web browser of their smartphone:

In order to stop sending user location and remove the user from the session, call the leaveUser() method:

session.leave(new ResponseListener() { ... });

session.leave(object: ResponseListener { ... })

To find an existing session, use the findSession() method with the corresponding session identifier:

Pathshare.client().findSession(identifier, new SessionResponseListener() {
    @Override
    public void onSuccess(Session session) {
        session.setSessionExpirationListener(
            new SessionExpirationListener() { ... }
        );
    }

    @Override
    public void onError(@NonNull Throwable throwable) { ... }
}

Pathshare.client().findSession(identifier, object: SessionResponseListener {
    override fun onSuccess(session: Session?) {
        session.sessionExpirationListener = SessionExpirationListener { ... }
    }

    override fun onError(throwable: Throwable) { ... }
})