NAV
shell obj-c swift java ruby python C#

Introduction

The Fracas Client API lets you sync your users’ app settings across devices.

We have Client Libraries available for download in Objective-C, Swift, Java and C#, which should be enough to get you up and running on most mobile platforms.

Common Parameters

With few exceptions, every call to the Fracas API should include the same three parameters. This makes it easy to use a client library, as most endpoint calls require no additional information.

Query Parameters

Parameter Description
publickey A valid public key associated with your account
appkey The App Key for your project
deviceid A temporarily-unique identifier generated by the device, as described in DeviceIDs.
devicekey (optional) A guaranteed unique identifier, returned by an AddDevice API call

Once known, DeviceKey should be used in place of DeviceID. If DeviceKey is specified, DeviceID is not required and will be ignored if supplied.

DeviceIDs

Two methods are available to identify a user device: DeviceID and DeviceKey.
The simple distinction between the two is that DeviceID is generated by the device itself, while DeviceKey is assigned by the Fracas API. In general, you should use DeviceKey whenever it is available, relying on DeviceID only when the device has not yet been connected to a Fracas APP, and therefore has not yet had a DeviceKey assigned.

DeviceID

A DeviceID may be any string that uniquely identifies a single device. Generally, it should be an identifier provided by the platform API, such as iOS’ identifierForAdvertising or Android’s Settings.Secure#ANDROID_ID. Failing that, a temporarily unique string such as a MAC address will work nicely.

Ideally a DeviceID should be something that will never change for a device, though in practice it need only survive long enough for the device to be connected to your app and receive a DeviceKey from the API.

DeviceKey

A DeviceKey is generated by the Fracas API as part of the AddDevice API call. It is guaranteed unique, and should be stored on the device and used for subsequent API calls once known.

Client Endpoints

GetDeviceStatus

curl "https://api.frac.as/v1/getdevicestatus" \
    -d publickey=pub_YOUR_PUBLIC_KEY \
    -d appkey=app_YOUR_APP_KEY \
    -d deviceid=USER_DEVICE_UDID

UNKNOWN

using Fracas.Client

FracasClient.PublicKey = "pub_YOUR_PUBLIC_KEY";
FracasClient.AppKey = "app_YOUR_APP_KEY";
var status = FracasClient.GetDeviceStatus();

This endpoint retrieves the connection status of the specified device.

HTTP Request

POST https://api.frac.as/v1/GetDeviceStatus

Query Parameters

This endpoint requires only the Common Parameters described above.

Device Status Codes

Code Description
Unknown This device has never before been seen, or is not associated with any devices connected to the specified project..
AutoConnectable This device has previously been connected to a device running the specified project. It may be connected to this project without further user intervention.
Connected This device has been successfully connected to this project.

GetDeviceCount

curl "https://api.frac.as/v1/getdevicecount" \
  -d publickey=pub_YOUR_PUBLIC_KEY \
  -d appkey=app_YOUR_APP_KEY \
  -d deviceid=USER_DEVICE_UDID

2

using Fracas.Client

FracasClient.PublicKey = "pub_YOUR_PUBLIC_KEY";
FracasClient.AppKey = "app_YOUR_APP_KEY";
var count = FracasClient.GetDeviceCount();

This endpoint retrieves the number of devices connected to this app by the owner of the specified device.

You’ll use this to check whether the user in question is approaching the limit you’ve set for the maximum number of devices per app (the default is 5).

HTTP Request

POST https://api.frac.as/v1/GetDeviceCount

Returns

2

Query Parameters

This endpoint requires only the Common Parameters described above.

PrepareAddDevice

curl "https://api.frac.as/v1/prepareadddevice" \
  -d publickey=pub_YOUR_PUBLIC_KEY \
  -d appkey=app_YOUR_APP_KEY \
  -d deviceid=USER_DEVICE_UDID

123123

using Fracas.Client

FracasClient.PublicKey = "pub_YOUR_PUBLIC_KEY";
FracasClient.AppKey = "app_YOUR_APP_KEY";
var count = FracasClient.PrepareAddDevice();



returns "123123"

This endpoint prepares the app to receive a connection from a new device on the same wifi network as the specified one. It returns a code that can be used to complete the connection.

HTTP Request

POST https://api.frac.as/v1/PrepareAddDevice

Returns

123123

Query Parameters

This endpoint requires only the Common Parameters described above.

AddDevice

curl "https://api.frac.as/v1/adddevice" \
  -d publickey=pub_YOUR_PUBLIC_KEY \
  -d appkey=app_YOUR_APP_KEY \
  -d deviceid=USER_DEVICE_UDID \
  -d unlockcode=123123


dev_1234123412341234

using Fracas.Client

FracasClient.PublicKey = "pub_YOUR_PUBLIC_KEY";
FracasClient.AppKey = "app_YOUR_APP_KEY";
var status = FracasClient.AddDevice("123123");



returns "dev_1234123412341234"

This endpoint will connect the specified device to another of the user’s devices. It returns a unique DeviceKey that should be stored within the app and used for future API calls.

HTTP Request

POST https://api.frac.as/v1/AddDevice

Returns

dev_1234123412341234

Query Parameters

This parameter is usually required to be passed in addition to the Common Parameters described above.

Parameter Description
unlockcode The unlock code returned from a recent PrepareAddDevive call. May be omitted if the device has returned the AutoConnectable status from GetDeviceStatus.

SetState

curl "https://api.frac.as/v1/setstate" \
  -d publickey=pub_YOUR_PUBLIC_KEY \
  -d appkey=app_YOUR_APP_KEY \
  -d deviceid=USER_DEVICE_UDID
  -d statekey=color
  -d statevalue=yellow


using Fracas.Client

FracasClient.PublicKey = "pub_YOUR_PUBLIC_KEY";
FracasClient.AppKey = "app_YOUR_APP_KEY";
var status = FracasClient.SetState("color", "yellow");

This endpoint sets the state data for the specified key for the user associated with this device.

HTTP Request

POST https://api.frac.as/v1/SetState

Query Parameters

These required parameters should be passed in addition to the Common Parameters described above.

Parameter Description
statekey A string key to identify the data being stored
statevalue The string content of the data to store

GetState

curl "https://api.frac.as/v1/getstate" \
  -d publickey=pub_YOUR_PUBLIC_KEY \
  -d appkey=app_YOUR_APP_KEY \
  -d deviceid=USER_DEVICE_UDID
  -d statekey=color


yellow


using Fracas.Client

FracasClient.PublicKey = "pub_YOUR_PUBLIC_KEY";
FracasClient.AppKey = "app_YOUR_APP_KEY";
var status = FracasClient.GetState("color");



returns "yellow"

This endpoint retrieves the state data stored in the specified key for the user associated with this device.

HTTP Request

POST https://api.frac.as/v1/GetState

Returns

yellow

Query Parameters

This required parameter should be passed in addition to the Common Parameters described above.

Parameter Description
statekey A string key to identify the data being retrieved

DeleteState

curl "https://api.frac.as/v1/deletestate" \
  -d publickey=pub_YOUR_PUBLIC_KEY \
  -d appkey=app_YOUR_APP_KEY \
  -d deviceid=USER_DEVICE_UDID
  -d statekey=color


using Fracas.Client

FracasClient.PublicKey = "pub_YOUR_PUBLIC_KEY";
FracasClient.AppKey = "app_YOUR_APP_KEY";
var status = FracasClient.DeleteState("color");

This endpoint deletes the state data stored in the specified key for the user associated with this device.

HTTP Request

POST https://api.frac.as/v1/DeleteState

Query Parameters

This required parameter should be passed in addition to the Common Parameters described above.

Parameter Description
statekey A string key to identify the data being deleted

DeleteDevice

curl "https://api.frac.as/v1/deletedevice" \
  -d publickey=pub_YOUR_PUBLIC_KEY \
  -d appkey=app_YOUR_APP_KEY \
  -d deviceid=USER_DEVICE_UDID


using Fracas.Client

FracasClient.PublicKey = "pub_YOUR_PUBLIC_KEY";
FracasClient.AppKey = "app_YOUR_APP_KEY";
var status = FracasClient.DeleteDevice();

This endpoint removes a device from the specified project.

HTTP Request

POST https://api.frac.as/v1/DeleteDevice

Query Parameters

This endpoint requires only the Common Parameters described above.

Errors

The Fracas API returns a status of -1 for any failed call, along with a short description of what went wrong. As in:

-1 invalid unlockcode

shell obj-c swift java ruby python C#