This legacy SDK will be deprecated on January 1, 2024.

Introduction

Supported Devices

• Mobile
• Mobile V2
• C6
• C8

Quick Start Guide

Understanding the Sample Project

Your app will send commands to, and receive callbacks from, BACtrack devices. In order to do this, you must first initialize a BacTrackAPI object with the following command call: mBacTrack = [[BacTrackAPI alloc] initWithDelegate:<BacTrackAPIDelegate> AndAPIKey:@"insertAPIKeyStringHere"]; This initializer method sets the specified delegate and checks with our server whether the included API Key is valid. In case your app has not been approved to use our SDK, the callback (void)BacTrackAPIKpiKeyDeclined:(NSString *)errorMessage will be called and must be implemented.

Once you've initialized your BacTrackAPI object, you can establish a BTLE connection between your iOS device and a BACtrack by executing the following command call on the BacTrackAPI object: connectToNearestBreathalyzer

Tapping on the "Take Test" button calls startCountdown on the BacTrackAPI object and initiates a series of callbacks on the BacTrackAPIDelegate shown below.

Starting a BAC test walks the user through 5 steps.

The test process consists of a series of five phases. At the start of every phase your <BacTrackAPIDelegate> receives the following callbacks:

1. Warming up (void)BacTrackCountdown:(NSNumber *)seconds executionFailure:(BOOL)failure This callback may be called many times and the <seconds> parameter is an estimated amount of seconds left until the next phase (BacTrackStart) begins.
2. Begin Blowing (void)BacTrackStart
3. Keep Blowing (void)BacTrackBlow: This callback may be called many times during the time that the user is blowing into the BACtrack.
4. Analyzing (void)BacTrackAnalyzing When this callback is called, the user can stop blowing.
5. Results (void)BacTrackResults:(CGFloat)bac

API Reference

Initialize class

-(id)initWithDelegate:(id<BacTrackAPIDelegate> )delegate AndAPIKey:(NSString*)api_key;

These methods represent the commands you can send to a BACtrack:

-(void)connectBreathalyzer:(Breathalyzer*)breathalyzer
    withTimeout:(NSTimeInterval)timeout

Delegate Reference

These methods represent all the messages you might get from the BACtrack.

-(void)BacTrackCountdown:(NSNumber*)seconds
        executionFailure:(BOOL)error

Other Connection Method

You can connect to a BACtrack manually

Normally, an app will set up a BTLE connection with the nearest BACtrack using the connectToNearestBreathalyzer command call. However, your app might want to connect with a selected BACtrack. To enable this functionality, you need to scan for nearby BACtracks using the startScan command call. The scan runs indefinitely until the command stopScan is called. During the scan, everytime your iOS device finds a BACtrack, the callback (void)BacTrackFoundBreathalyzer:(Breathalyzer*)breathalyzer is called. Our sample app implements this by adding the breathalyzer to a breathalyzers array, which is then used as the data source for a table view that lists all the nearby breathalyzers.

A list of nearby BACtracks in the Sample App

You can distinguish between BACtracks with the following attributes:

• Breathalyzer.perpipheral.name
• Breathalyzer.uuid

After isolating the Breathalyzer object that you want, you can connect with it by providing the Breathalyzer object as an argument to the following command call: (void)connectBreathalyzer:(Breathalyzer*)breathalyzer withTimeout:(NSTimeInterval)timeout

Installation

The BACtrack API consists of a static library (.a file) and a header file (.h file). To use the SDK, your app must link with our static library.

Add the .a library file in build phases.

Lastly, in Build Settings > Linking > Other Linker Flags, add the following flags:

• -ObjC
• -all_load

Quick Start Guide (Android)

Your app will send commands, and recieve callbacks from your BACtrack device. In order to do this, you must first create a BacTrackAPI object with the following constructor: mAPI = new BACtrackAPI(this, mCallbacks, apiKey);. This constructor creates a BACtrackAPI object with the passed in callbacks and also checks with our server whether the included API Key is valid. In case your app has not been approved to use our SDK, the callback void BACtrackAPIKeyDeclined(String errorMessage) will be called and must be implemented.

Once you've created your BacTrackAPI object, you can establish a BTLE connection between your Android device and your BACtrack by executing the following command call on the BACtrackAPI object: public void connectToNearestBreathalyzer()

Tapping on the "Take Test" button calls public boolean startCountdown() on the BacTrackAPI object and initiates a series of callbacks on the BacTrackAPIDelegate shown below.

The test process consists of a series of five phases. At the start of every phase your <BacTrackAPIDelegate> receives the following callbacks:

1. Warming up void BACtrackCountdown(int currentCountdownCount) This callback may be called repeatedly and the <currentCountdownCount> parameter is an estimated amount of seconds left until the next callback (BacTrackStart) is called.
2. Begin Blowingvoid BACtrackStart()
3. Keep Blowingvoid BACtrackBlow(float breathFractionRemaining) This callback may be called repeatedly during the time that the user is expected to blow into the BACtrack device.
4. Analyzingvoid BACtrackAnalyzing() When this callback is called, the user can stop blowing.
5. Resultsvoid BACtrackResults(float measuredBac)

API Reference (Android)

Constructor to be used with the public SDK.

public BACtrackAPI(Context context, final BACtrackAPICallbacks bacTrackAPICallbacks, String apiKey)

These methods represent the commands you can send to the BACtrack.

Callback Reference (Android)

These methods represent all the messages you might get from the BACtrack.

Web API Overview

BACtrack users have store hundreds of thousands of BAC readings to the cloud. BAC readings contain rich metadata like location, photos, and notes. Many users opt in to allow readings to be viewed anonymously. This unique dataset can be accessed by developers for use in statistcal analysis, data mashups, or use in your app. You can view some examples of the data in action at the BACtrack Consumption Report and BACtrack WorldView. In your own app, you can authentice users to let them view their account data.

Authentication

The BACtrack data API uses OAuth 1.0a. OAuth is a protocol that allows the user grant your app access to our web service on his behalf without telling you his login credentials. OAuth defines a workflow that allows the user to log in to our site at your request to create an access token that will allow you to request data from the service on his behalf.

OAuth Signing

These docs don't describe how to sign each request. There is a description of the process at https://oauth.net/core/1.0a/#signing_process. However, most developers do not implement OAuth signing themselves since there are several available libraries. In python, people typically use OAuth2 (In spite of its name, this library is for OAuth 1.0a).

Steps to Obtain an Access Token

As you read the overview of the OAuth authentication protocol below, it might help to follow along on this diagram from oauth.net: https://oauth.net/core/diagram.png

1. The Consumer (your app) requests a Request Token from the Provider (our service) at https://mobile.bactrack.com/oauth/request_token/. The Consumer's request must be signed with a valid Consumer Secret (see above for a discussion of signing). The request does not need to include any oauth_token in the header. The response will consist of a Request Token and a Request Token Secret.
2. The Consumer requests (and shows to the user) the login (authorization) page at https://mobile.bactrack.com/oauth/authorize/. The request for this page should use the Request Token as its oauth_token and compute the oauth_signature using the Request Token Secret.
3. After the user has logged in and authorized the Consumer, the Consumer can now use the validated Request Token to request an Access Token at https://mobile.bactrack.com/oauth/access_token/. This request should be signed using the Request Token Secret. The response will consist of an Access Token and Access Token Secret.

For all of these steps and for general API usage, the oauth parameters should be passed via the HTTP Authorization header. If the HTTP Authorization header is not available, we also accept these parameters as url-encoded query string parameters. The parameter names are as follows:

Note: In OAuth jargon, a key is like a username, and a secret is the corresponding password. Important: You must set the content-type to json in the header of every request: Content-Type: application/json.
Alternatively, you can add ?format=json to all requests.

BAC Readings

Readings are the backbone of the BACtrack data API. They provide insight into user activity and contain a variety of interesting data sets.

User Readings

User readings are readings that belong to a particular users. These readings may or may not be publicly shared by the user. To access the private readings for a user, you must sign the request with a validated Access Token.

Query String Filter Parameters:

Sample Request with Timestamp Filters

Content-Type: application/json; charset=utf-8
Authorization: {oauth header goes here}
GET https://mobile.bactrack.com/v1/users/1/readings/timestamp__gte=2010-11-16 14:17:00&timestamp__lte=2010-11-16 14:22:00

Sample Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  count:1,
  readings:
   [
      {
        "id": 123,
        "date": "2010-11-16 14:18:00",
        "location": [47.123, 128.112],
        "bac": 0.021,
        "verified", false,
        "drinks":
         [
           "martini",
           "bourbon"
         ],
        "notes":
        [
          "Love whiskey"
        ],
        "photos":
        [
        ]
     }
   ]
}

Sample Request with Center and Radius Filter

Content-Type: application/json; charset=utf-8
Authorization: {oauth header goes here}
GET https://mobile.bactrack.com/v1/users/{id}/readings?lat_center=47.123&lng_center=128.112&radius_meters=100

Sample Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  count:1,
  readings:
   [
      {
        "id": 123,
        "date": "2010-11-16 14:18:00",
        "location": [47.123, 128.112],
        "bac": 0.021,
        "verified", false,
        "drinks":
         [
           "martini",
           "bourbon"
         ],
        "notes":
        [
          "Love whiskey"
        ],
        "photos":
        [
        ]
     }
   ]
}

Public Readings

Note: Since these resources give you readings that users have made public, you don't need to sign these requests with a validated Access Token. You can just sign them with your Consumer Key and Secret (like when you're requesting a request token).

GET https://mobile.bactrack.com/v1/readings

Query String Filter Parameters:

Sample Request with Location Filter

Content-Type: application/json; charset=utf-8
Authorization: {oauth header goes here}
GET https://mobile.bactrack.com/v1/readings?lat_center=47.123&lng_center=128.112&radius_meters=100

Sample Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
  count:1,
  readings:
   [
      {
        "id": 123,
        "date": "2010-11-16 14:18:00",
        "location": [47.123, 128.112],
        "bac": 0.021,
        "verified", false,
        "drinks":
         [
           "martini",
           "bourbon"
         ],
        "notes":
        [
          "Love whiskey"
        ],
        "photos":
        [
        ]
     }
   ]
}

Return a Single Public Reading

GET https://mobile.bactrack.com/v1/readings/id

Sample Request

Content-Type: application/json; charset=utf-8
Authorization: {oauth header goes here}
GET https://mobile.bactrack.com/v1/readings/123

Sample Response:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

  {
    "id": 123,
    "date": "2010-11-16 14:18:00",
    "location": [47.123, 128.112],
    "bac": 0.021,
    "verified", false,
    "drinks":
     [
       "martini",
       "bourbon"
     ],
    "notes":
    [
      "Love whiskey"
    ],
    "photos":
    [
    ]
 }

Photos are requested via a normal GET request that does not need to be signed with OAuth. The URLs for the photos are available in "photos" section of any Reading resource.