Quick Start
Login to Built.io Backend management console, and create an application:
When you create an app, you receive an api_key:
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
- Download the iOS SDK.
- Drag-and-drop the BuiltIO.framework into your project folder in Xcode.
- 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.
- Next, click the project icon in the project navigator.
- Select your app under TARGETS in the project editor.
- Under
Build Phases
tab, open up Link Binary With Libraries. - Click the add
(+)
button to add libraries. - 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)
- In your target, select the
Build Settings
tab, add the-ObjC
flag to Other Linker Flags.
Intialization
- In your
AppDelegate.m
import the file:
#import <BuiltIO/BuiltIO.h>
You can also import as a Module:@import BuiltIO
- 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
- Download the iOS SDK.
- Drag-and-drop the BuiltIO.framework into your project folder in Xcode.
-
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.
- Next, click the project icon in the project navigator.
- Select your app under TARGETS in the project editor.
- Under Build Phases tab, open up Link Binary With Libraries.
- Click the add (+) button to add libraries.
- 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)
-
In your target, select the
Build Settings
tab, add the-ObjC
flag to Other Linker Flags. - 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.
Name 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"
You 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
-
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>
You can also import as a Module in your swift file:
-
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");
import BuiltIO
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
- Download the Android SDK .
- The zip file contains the Built.io Backend SDK, User Interface Kit and Starter Kit. Extract the built.io zip file to begin.
- Android Studio
- Copy Built.io-xxx.aar to your project's libs folder.
- Add dependency code in your build.gradle file.
- Eclipse
- Copy Built.io-xxx-javadoc, Built.io-xxx.jar, Built.io-xxx.jar.properties to your project's libs folder.
- Add jar references in the project's properties --> Java Build Path --> Libraries tab.
Your project in that folder will look like this:
- Manifest Permissions The following permissions are required for the SDK to work properly
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:

<!-- 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
- Download the JS SDK. Unzip and copy it to a folder that is easy to access from your HTML file.
- 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>
- 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
- 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'.
- Add the following statement before your class definition:
using BuiltSDK;
- 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