Quick Start

Login to Built.io Backend management console, and create an application:

Create application

When you create an app, you receive an api_key:

Saved application

Use it to identify the app to the SDK during its initialization.

Dive in quickly by following these guides for iOS (Objective-C), iOS (Swift), Android, JavaScript, Xamarin and REST!

iOS (Objective-C)

Installing the iOS SDK

Cocoapods (Recommended)

Add the following lines to your Podfile in your desired target: 

   target '<iOSTargetName>' do
   platform :ios, '7.0'
   pod 'BuiltIOBackend'
   end

   target '<WatchAppTarget>' do
   platform :ios, '7.0'
   pod 'BuiltIOBackend'
   end

Run pod install, and you should now have the latest BuiltIOBackend release.

Manual

  1. Download the iOS SDK.
  2. Drag-and-drop the BuiltIO.framework into your project folder in Xcode.
    Xcode framework
  3. A window for choosing options to add files appears. Click the Destination checkbox to Copy items into destination group's folder. The Built.io Backend SDK is now added to your project.
    Xcode project options
  4. Next, click the project icon in the project navigator.
  5. Select your app under TARGETS in the project editor.
  6. Under Build Phases tab, open up Link Binary With Libraries.
  7. Click the add (+) button to add libraries.
  8. Add the following libraries according to iOS and watchOS targets:
    • Accounts.framework (iOS)
    • CFNetwork.framework (iOS)
    • CoreGraphics.framework (iOS|WatchOS)
    • CoreLocation.framework (iOS|WatchOS)
    • CoreTelephony.framework (iOS)
    • MobileCoreServices.framework (iOS|WatchOS)
    • Security.framework (iOS|WatchOS)
    • Social.framework (iOS)
    • SystemConfiguration.framework (iOS)
    • libicucore.tbd (iOS|WatchOS)
    • libsqlite3.tbd (iOS|WatchOS)
    When you have all the libraries, your project will look like the following:
    Xcode project summary
  9. In your target, select the Build Settings tab, add the -ObjC flag to Other Linker Flags.

Intialization

  1. In your AppDelegate.m import the file:
    #import <BuiltIO/BuiltIO.h>
    You can also import as a Module: 
    @import BuiltIO
  2. Now you need to set up your application api_key. This can be done in the following manner:
    BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"API_KEY"];

You are now all set to use Built.io Backend for iOS development.

Creating Objects

The BuiltObject class is used to create, update and delete objects on Built.io Backend. Here's how you can create an object: 

// 'blt5d4sample2633b' is a dummy Application API key
// 'student' is a uid of a class on Built.io Backend
BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"blt5d4sample2633b"];
BuiltClass *studentClass = [builtApplication classWithUID:@"student"];
BuiltObject *studentObject = [studentClass object];
studentObject[@"name"] = @"Ricky";
studentObject[@"age"] = @(23);
studentObject[@"gender"] = @"male";
studentObject[@"id"] = @(8)
[studentObject save:^(BuiltResponseType responseType, NSError *error) {
    if (error == nil) {
        // object is created successfully
    }else {
        // there was an error in creating the object
        // error.userinfo contains more details regarding the same
    }
}];

User Management

The BuiltUser class is used to login, logout, and register users in an application. Lets take a look at how you would login a user into your app: 

// 'blt5d4sample2633b' is a dummy Application API key
BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"blt5d4sample2633b"];
BuiltUser *userObject = [builtApplication user];
// here "test@mail.com" is a valid email id of your user
// and "password", the corresponding password
[userObject loginWithEmail:@"test@mail.com" andPassword:@"password" completion:^(BuiltResponseType responseType, NSError *error) {
    if (!error) {
        // user has logged in successfully
    }else {
        // login failed
        // error.userinfo contains more details regarding the same
    }
}];

Querying Classes

See how to query a class to fetch objects satisfying a certain condition. 

// 'blt5d4sample2633b' is a dummy Application API key
// 'student' is a uid of a class on Built.io Backend
BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"blt5d4sample2633b"];
BuiltClass *studentClass = [builtApplication classWithUID:@"student"];
BuiltQuery *studentQuery = [studentClass query];
[studentQuery whereKey:@"name" equalTo:@"John"];
[studentQuery exec:^(BuiltResponseType type, BuiltQueryResult *result, NSError *error) {
    if (!error) {
        // the query has executed successfully.
        // result.getResult() will contain a array of objects as that satisfy the conditions
    }else {
        // query execution failed.
        // error.userinfo contains more details regarding error
    }
}];

iOS (Swift)

Installing the iOS SDK

Cocoapods (Recommended)

Add the following lines to your Podfile in your desired target: 

   target '<iOSTargetName>' do
   platform :ios, '7.0'
   pod 'BuiltIOBackend'
   end

   target '<WatchAppTarget>' do
   platform :ios, '7.0'
   pod 'BuiltIOBackend'
   end

Run pod install, and you should now have the latest BuiltIOBackend release.

Manual

  1. Download the iOS SDK.
  2. Drag-and-drop the BuiltIO.framework into your project folder in Xcode.
    Xcode framework
  3. A window for choosing options to add files appears. Click the Destination checkbox to Copy items into destination group's folder. The Built.io Backend SDK is now added to your project.
    Xcode project options
  4. Next, click the project icon in the project navigator.
  5. Select your app under TARGETS in the project editor.
  6. Under Build Phases tab, open up Link Binary With Libraries.
  7. Click the add (+) button to add libraries.
  8. Add the following libraries:
    • Accounts.framework (iOS)
    • CFNetwork.framework (iOS)
    • CoreGraphics.framework (iOS|WatchOS)
    • CoreLocation.framework (iOS|WatchOS)
    • CoreTelephony.framework (iOS)
    • MobileCoreServices.framework (iOS|WatchOS)
    • Security.framework (iOS|WatchOS)
    • Social.framework (iOS)
    • SystemConfiguration.framework (iOS)
    • libicucore.tbd (iOS|WatchOS)
    • libsqlite3.tbd (iOS|WatchOS)
    When you have all the libraries, your project will look like the following:
       Xcode project summary
  9. In your target, select the Build Settings tab, add the -ObjC flag to Other Linker Flags.
  10. In order to use built framework, you will have to create a bridging header file. Click on File -> New -> File… and select “Header File" in the “Source" tab. Xcode project configurationName this file "BridgeHeader.h", for instance. Open your project Build Settings and search for “Bridging". Edit the key “Objective-C Bridging Header" to "your_project_name_path/BridgeHeader.h" Xcode project nameYou are now ready to add your imports into your BridgeHeader.h file for the built framework you want to use, just as you would do in your .pch file.

Intialization

  1. In your BridgeHeader.h import the file: 
    // Use this file to import your target's public headers that you like to expose to Swift.
#import <BuiltIO/BuiltIO.h>
    2. You can also import as a Module in your swift file: 
    import BuiltIO
  2. Now you need to set up your application api_key. This can be done in the following manner: 
    var builtApplication:BuiltApplication = Built.applicationWithAPIKey("API_KEY");

You are now all set to use Built.io Backend for iOS development.

Creating Objects

The BuiltObject class is used to create, update and delete objects on Built.io Backend. Here's how you can create an object: 

// 'blt5d4sample2633b' is a dummy Application API key
// 'student' is a uid of a class on Built.io Backend
var builtApplication:BuiltApplication = Built.applicationWithAPIKey("blt5d4sample2633b")
var studentClass:BuiltClass = builtApplication.classWithUID("student")
var studentObject:BuiltObject = studentClass.object()
studentObject["name"] = "Ricky"
studentObject["age"] = NSNumber(integer:1)
studentObject["gender"] = "male"
studentObject["id"] = NSNumber(integer:1)
studentObject.save { (responseType:BuiltResponseType, error:NSError!) -> Void in
    if (error == nil) {
        // object is created successfully
    }else {
        // there was an error in creating the object
        // error.userinfo contains more details regarding the same
    }
}

User Management

The BuiltUser class is used to login, logout, and register users in an application. Lets take a look at how you would login a user into your app: 

// 'blt5d4sample2633b' is a dummy Application API key
var builtApplication:BuiltApplication = Built.applicationWithAPIKey("blt5d4sample2633b")
var userObject:BuiltUser = builtApplication.user()
userObject.loginWithEmail("test@mail.com", andPassword: "password") { (responseType:BuiltResponseType, error:NSError!) -> Void in
    if (error == nil) {
        // user has logged in successfully
    }else {
        // login failed
        // error.userinfo contains more details regarding the same
    }
}

Querying Classes

See how to query a class to fetch objects satisfying a certain condition. 

// 'blt5d4sample2633b' is a dummy Application API key
// 'student' is a uid of a class on Built.io Backend
var builtApplication:BuiltApplication = Built.applicationWithAPIKey("blt5d4sample2633b")
var studentClass:BuiltClass = builtApplication.classWithUID("student")
var studentQuery:BuiltQuery = studentClass.query()
studentQuery.whereKey("name", equalTo:"John")
studentQuery.exec { (responseType:BuiltResponseType, result:BuiltQueryResult!, error:NSError!) -> Void in
    if (error == nil) {
        // the query has executed successfully.
        // result.getResult() will contain a array of objects as that satisfy the conditions
    }else {
        // query execution failed.
        // error.userinfo contains more details regarding error
    }
}

Android

Installing the Built.io Backend library

  1. Download the Android SDK .
  2. The zip file contains the Built.io Backend SDK, User Interface Kit and Starter Kit. Extract the built.io zip file to begin.
  3. Android Studio
    1. Copy Built.io-xxx.aar to your project's libs folder.
    2. Add dependency code in your build.gradle file.
    4.     repositories {
        flatDir {
            dirs 'libs'
        }
    }
    dependencies {compile 'com.raweng.built:Built.io-x.x.x:x.x.x@aar'}

               Your project in that folder will look like this:

    Built.io starter kit
  4. Eclipse
    1. Copy Built.io-xxx-javadoc, Built.io-xxx.jar, Built.io-xxx.jar.properties to your project's libs folder.
    2. Add jar references in the project's properties --> Java Build Path --> Libraries tab.
      Your project in that folder will look like this:

    5. Eclipse lib structure

  5. Manifest Permissions The following permissions are required for the SDK to work properly
<!-- Allows applications to connent network (Required) -->
<uses-permission android:name="android.permission.INTERNET" />

<!-- Allows applications to access information about networks (Required) -->
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

<!-- Allows read only access to phone state. (Required For analytics) -->
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

<!-- Allows access to the list of accounts in the Accounts Service. 
(Required For Oauth login and Google login using BuiltUILoginController) -->
<uses-permission android:name="android.permission.GET_ACCOUNTS" />

<!-- Allows an application to request authtokens from the AccountManager. 
(Required For Oauth login and Google login using BuiltUILoginController) -->
<uses-permission android:name="android.permission.USE_CREDENTIALS" />

<!-- Allows an app to access precise location from location sources. (Required For location) -->
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />

<!-- Allows an app to access approximate location derived from network location sources. (Required For location) -->
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" />

<!-- Allow the application to access Google web-based services -->
<uses-permission android:name="com.google.android.providers.gsf.permission.READ_GSERVICES" />

Add the following receivers to your application node 

<!-- To check network availability. Called every time when network 
connection state changes -->
<receiver
    android:name="com.raweng.built.ConnectionStatus"
    android:enabled="true" >
    <intent-filter>
        <action android:name="android.net.conn.CONNECTIVITY_CHANGE" >
        </action>
    </intent-filter>
</receiver>
<!-- To delete expired cache from built cache folder -->
<receiver
    android:name="com.raweng.built.BuiltClearCache"
    android:enabled="true" >
    <intent-filter>
        <action android:name="StartClearingCache" >
        </action>
    </intent-filter>
</receiver>
<!-- add for new upgradation of google play services if required -->
<meta-data
  android:name="com.google.android.gms.version"
  android:value="@integer/google_play_services_version" />
<activity
       android:name="com.raweng.built.userInterface.UIAndroidExplorerScreen"
       android:label="@string/app_name" >
 </activity>
<activity
    android:name="com.raweng.built.userInterface.BuiltTwitterLoginActivity"
    android:screenOrientation="portrait" >
<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:host="twitterlogin" android:scheme="x-oauthflow-twitter" />
</intent-filter>
</activity>

It's now time to set up the api_key for your application. Use the initializeWithApiKey(Context context, String apiKey, String appUid) method of the Built.io Backend class in your java code as follows: 

BuiltApplication builtApplication  = Built.application(context,"API_KEY");

Congratulations! You are all set to get started with Built.io Backend.

Working with BuiltObject

BuiltObject is used to create, update and delete objects on Built.io Backend. Here's how to create an object: 

// 'blt5d4sample2633b' is a dummy Application API key
// 'classWithUid("class_uid").object() returns an 'BuiltObject' instance.
// 'student' is a uid of a class on Built.io Backend.

BuiltApplication builtApplication   = Built.application(context,"blt5d4sample2633b");
BuiltObject students   = builtApplication.classWithUid("student").object();

// "id" is the field uid, we set it to '8'
students.set("id", 8);
students.set("name", "Ricky");
students.set("gender", "male");
students.set("age", 23);

students.save(new BuiltResultCallBack() {
    @Override
    public void onCompletion(BuiltResponseType responseType, BuiltError error) {
        if(error == null){
           // object is created successfully
        }else{
           // some error has occurred.
           // refer to the 'error' object for more details.
        }
    }
});

Working with BuiltUser

Use the BuiltUser class to log in, logout, and register users in your application.

You can log in an application user with the following code: 

// 'blt5d4sample2633b' is a dummy Application API key
BuiltApplication builtApplication  = Built.application(context, "blt5d4sample2633b");
BuiltUser user        =  builtApplication.user();

user.login("test@email.com", "password", new BuiltResultCallBack() {
        // here "test@email.com" is a valid email id of your user.
        // and "password", the corresponding password.
    @Override
    public void onCompletion(BuiltResponseType responseType, BuiltError error) {
      if(error == null){
        // user has logged in successfully
      }else{
        // login failed
        // refer to the 'error' object for more details
      }
    }
});

Working With BuiltQuery

It should be no surprise that you use BuiltQuery to search classes. Here's how you can retrieve objects of a class: 

// 'blt5d4sample2633b' is a dummy Application API key
// 'student' is a uid of a class on Built.io Backend.

BuiltApplication builtApplication = Built.application(context, "blt5d4sample2633b");
BuiltQuery query     = builtApplication.classWithUid("student").query();

query.exec(new QueryResultsCallBack() {
    @Override
    public void onCompletion(BuiltResponseType responseType, BuiltQueryResult queryResultObject, BuiltError error) {
        if(error == null){
           // the queryResultObject will contain the objects of the class
           List<BuiltObject> objects = queryResultObject.getResultObjects();
        }else{
           // query failed
           // refer to the 'error' object for more details
        }
    }
});

JavaScript

Importing the SDK into the HTML file

  1. Download the JS SDK. Unzip and copy it to a folder that is easy to access from your HTML file.
  2. Add the following tag to the header of your HTML file:
    <script src="(path to the Built.io Backend JavaScript SDK)/built_rt.min.js"></script>
  3. You are now ready to set up your application. To initialize the application with API key follow the code  below: 
    var app = Built.App('application_api_key');

Congratulations! You're all set to use Built.io Backend.

Creating Objects in Built.io Backend

Use the Built.Object class to create, update and delete objects in Built.io Backend. Here's how we create an object 

// 'blt5d4sample2633b' is a dummy Application API key
// 'Class('class_name').Object returns a Object constructor
// 'student' is a uid of a class on Built.io Backend
var Student = Built.App('blt5d4sample2633b').Class('student').Object;
var student = Student();

student = student.assign({
  name: 'ricky',
  age: '23',
  gender: 'male',
  id: '8'
});

student
.save()
.then(function(student) {
  // object created successfully
  console.log(student.toJSON());
}, function(err) {
  // some error has occurred
  // refer to the 'error' object for more details
});

User Management in Built.io Backend

Use the Built.User class to login, logout, and register users in an application. You may log in an application user with the following code: 

// 'blt5d4sample2633b' is a dummy Application API key
var user = Built.App('blt5d4sample2633b').User();
user.login('test@email.com', 'password')
.then(function(user) {
  // user logged in successfully
  console.log(user.toJSON())
}, function(error) {
  // some error has occurred
  // refer to the 'error' object for more details
});

Querying objects of a class

You can query objects of a class with certain conditions. 

// 'blt5d4sample2633b' is a dummy Application API key
// 'student' is uid of an class on Built.io Backend
var query = Built.App('blt5d4sample2633b').Class('student').Query();
// we query for the student with the 'name' 'John'
query
.where('name', 'John')
.exec()
.then(function(students) {
  // students is an array of SDK objects
  // logging the first student's details
  console.log(students[0].toJSON());
}, function(error) {
  // some error has occurred
  // refer to the 'error' object for more details
});

Xamarin

Installing the Xamarin SDK

  1. To use this SDK in Xamarin, follow the steps given below:
    • Create new MonoDroid or MonoTouch project.
    • Expand project under 'Solution Explorer'.
    • Now Right click on 'Components' directory.
    • And select 'Get More Components' option.
    • In 'Search Component', search for 'built.io'.
    • Select 'built.io' component from search list.
    • Now click on 'Add to App' button, it will add 'built.io' component to project.
    • Alternatively, you can download component from 'xamarin components website'.
  2. Add the following statement before your class definition: 
    using BuiltSDK;
  3. You are now ready to set up your application. Use the initialize static method for the Built class as follows:
    var app = Built.App("api_key");

Congratulations! You're all set to use Built.io Backend.

Creating Objects in Built.io Backend

Use the BuiltObject class to create, update and delete objects in Built.io Backend. Here's how we create an object: 

// 'blt5d4sample2633b' is a dummy Application API key
// 'Class('class_uid').Object() returns a Object constructor
// 'student' is a uid of a class on Built.io Backend
var student = Built.App("blt5d4sample2633b").Class("student").Object();
student["name"] = "ricky";
student["age"] = 23;
student["gender"] ="male";
student["id"] = 8;
student.Save().ContinueWith(objectTask=>
{
    if(objectTask.IsFaulted)
    {
        // some error has occurred
        // refer to the objectTask.Exception.Flattern().InnerException for more details
    }
    else
    {
        // object created successfully
    }
});

User Management in Built.io Backend

Use the BuiltUser class to login, logout, and register users in an application. You can log in as an application user with the following code: 

// 'blt5d4sample2633b' is a dummy Application API key
var user = Built.App("blt5d4sample2633b").User();
user.Login("test@email.com", "password").ContinueWith((userTask) => {
    if (userTask.IsFaulted) 
    {        
        // some error has occurred
        // refer to the userTask.Exception.Flattern().InnerException for more details
    }
    else 
    {
        // user logged in successfully
    }
});

Querying objects of a class

You can also query a class to fetch objects satisfying a certain condition: 

// 'blt5d4sample2633b' is a dummy Application API key
// 'student' is uid of an class on Built.io Backend
var query = Built.App("blt5d4sample2633b").Class("student").Query();
// we query for the student with the name "John"
query.Where("name", "John");
query.Exec().ContinueWith(queryTask=>
{
    if(queryTask.IsFaulted)
    {
        // some error has occurred
        // refer to the queryTask.Exception.Flattern().InnerException for more details
    }    
    else
    {
        // the queryTask.Result will contain the objects of the class
    }
});

REST

Overview

Built.io Backend features comprehensive REST APIs for your application.

The base URL for all the endpoints mentioned is:

<a href="https://api.built.io" target="_blank">https://api.built.io</a>

We use the 'curl' tool here to make REST calls. Alternatively, you may use any HTTP library to make calls to Built.io Backend.

All calls should be made using the 'application/json' content-type.

Creating an object

For an application with the api_key as 'sample_api_key', we create an object in the class 'student': 

curl -i -X POST \
-H "application_api_key: sample_api_key" \
-H "Content-Type: application/json" \
-d '{
       "object": {
           "name": "John"
       }
    }' \
https://api.built.io/v1/classes/student/objects

'v1' indicates we are using version 1 of the API.

Logging in a user

Here we login a user 'john@malkovich.com', with the password 'password': 

curl -i -X POST \
-H "application_api_key: sample_api_key" \
-H "Content-Type: application/json" \
-d '{
    "application_user": {
            "email": "john@malkovich.com",
            "password": "password"
        }
    }' \
https://api.built.io/v1/application/users/login

Querying objects of a class

In this example, we query the 'student' class for students named 'John'. 

curl -i -X GET \
-H "application_api_key: sample_api_key" \
-H "Content-Type: application/json" \
-G \
--data-urlencode 'query={"name": "John"}' \
https://api.built.io/v1/classes/student/objects