Asset Tracking

Using the example apps

Asset Tracking SDK repositories provide example apps for subscribing and publishing. You can test out the sample apps using the emulator provided with the developer tools for your platform.

Using the example apps

The following procedure uses Android Studio by way of example, you can also use other tools such as Gradle.

1. Download and install Android Studio, if not already available on your development system.
2. Make sure Android SDK build tools are installed. You’ll need to accept the licenses.

Installed SDK build tools

3. Clone the Ably Asset Tracking SDK Android GitHub repo.
4. Open the cloned directory in Android Studio.
5. From the drop-down menu in Android Studio, select the app to run: publishing-example-app and a device to run it on, then click Run.

Select the publishing app

The app builds and the emulator is displayed. It takes a while to boot up.

6. By default the location source that the app will use for updates is set to phone. Using the Settings button in the app you can also select an Ably channel, or an S3 file as the source. The S3 file is a location history file downloaded from AWS S3 that replays the location data.

How to select location source

7. Assuming you keep the default option, you can then create a simulated route in the Extended controls. In the emulator, use the Extended controls to create a route. This route is the simulated route that the publisher (asset) will follow.

Extended controls

8. Start the route.
9. In the publishing app click ‘+’ to add a trackable.
10. Enter a tracking ID and click Add.
11. Run the subscribing app on an additional device.
12. Enter the tracking ID.
13. The asset will be displayed on the map.

The following screenshot shows the example apps running:

Example apps running

Using the example apps

1. Clone the Ably Asset Tracking SDK Swift GitHub repo.
2. Open AblyAssetTracking.xcworkspace in Xcode. This workspace includes a Swift package containing the SDKs, and several example apps.
3. Configure your ~/.netrc file with your Mapbox secret access token that enables you to download the Mapbox SDK. You can find instructions on how to do this in the Mapbox docs.
4. Copy the Examples/Example.Secrets.xcconfig file to Example/Secrets.xcconfig.
5. In Example/Secrets.xcconfig, configure your ABLY_API_KEY and MAPBOX_ACCESS_TOKEN. This is the public Mapbox token, which you can find on your Mapbox account’s token page.
6. Select the PublisherExample scheme, choose an iOS simulator or device, and then press the run button. The following screen displays:

Provide a tracking ID

7. Click the Ask for location permissions button and grant the appropriate permissions.
8. Enter a tracking ID for the asset.
9. Ensure that the location source is set to “Phone”.
10. In the Simulator > Features > Location menu, select a sample route, such as “Freeway drive”.
11. Click the Start publishing button. The publisher starts broadcasting location data for the selected route:

Starting the Publisher Example app

12. In Xcode, run the SubscriberExample project, with a suitable target device.
13. When the target device loads, enter the same tracking ID that you provided in step 8 and click Start Tracking. The subscribing device receives updates from the publishing device and plots them on the map:

Publisher and subscriber apps running together

Using the example apps

The JavaScript example app only supports the Subscribing SDK. To use it, you must first run one of the publishing example apps to generate location data.

1. Clone the Ably Asset Tracking SDK JavaScript GitHub repo.
2. In the root directory of the project, install the SDK dependencies:

npm install

3. Then, build the SDK:

npm run build

4. Change into the examples/subscribing-example-app directory and install the example app’s dependencies:

npm install

5. Create a .env file in the root of the example app and configure it with your Ably API key:


6. Open your browser and visit http://localhost:5000:

Select map provider

7. Select your preferred map provider (Google Maps or Mapbox) and enter your provider’s API key when prompted.

8. Enter the ID of the asset you want to track:

Select trackable ID

9. The example app receives updates from the publisher and shows the current location of the asset on the map:

Example app running

See also

API reference

Need help?

If you need any help with your implementation or if you have encountered any problems, do get in touch. You can also quickly find answers from our knowledge base, and blog.