Built.io Backend Reference

Overview

Built.io Backend provides iOS SDK for users. Let us quickly understand the process to install and initialize this SDK, as well as the other features it provides.

Important Changes:

Built.io Backend has depcreated the use of GroupMultiple. For a detailed explaination please read through this blog post.

Installation

To setup Built.io Backend iOS SDK on Xcode, follow the steps given below.

CocoaPods (Recommended)

Add the following line 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 Latest iOS SDK release and extract the zip file to your local disk.

  2. Drag and drop BuiltIO.framework into your project folder in Xcode.

    A window will appear, prompting you to choose one of the options for adding files. Click the ‘Destination’ checkbox to copy items into the destination group’s folder. This will add the SDK to your project.

  3. In the project editor, select your app under TARGETS. Under the General tab, open Linked Frameworks and Libraries and 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.dylib (iOS|WatchOS)
    • libsqlite3.dylib (iOS|WatchOS)
  4. In your target app, click on the Build Settings tab and add the -ObjC flag to Other Linker Flags.

Import Header/Module

You can import header file in Objective-C project as:

#import <BuiltIO/BuiltIO.h>

You can also import as a Module:

//Obj-C
@import BuiltIO

//Swift
import BuiltIO

Initialization

The initialization process for each module is briefly explained below.

BuiltApplication

To initialize an app, use applicationForApiKey: method on the ‘Built’ class and set the application’s API key.

//'blt5d4sample2633b' is dummy Application API key
//Obj-C
BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"blt5d4sample2633b"];

//Swift
var builtApplication:BuiltApplication = Built.applicationWithAPIKey("blt5d4sample2633b")
BuiltClass

BuiltApplication can have multiple classes. A BuiltApplication instance has method classWithUID: that accepts the uid of the BuiltClass whose instance has to be created.

// 'project' is a uid of a class on Built.io Backend
//Obj-C
BuiltClass *projectClass = [builtApplication classWithUID:@"project"];

//Swift
var projectClass:BuiltClass = builtApplication.classWithUID("project")
BuiltObject

BuiltObject is an instance of a BuiltClass. A BuiltClass instance has method object and objectWithUID:. The objectWithUID: accepts an existing object’s uid to initialize a new BuiltObject.

//Obj-C
BuiltObject *projectObject = [projectClass object];

//'bltb6202sample73a1' is dummy project uid
BuiltObject *existingProjectObject = [projectClass objectWithUID:@"bltb6202sample73a1"]; 

//Swift
var projectObject:BuiltObject = projectClass.object()

//'bltb6202sample73a1' is dummy project uid
var existingProjectObject:BuiltObject = projectClass.objectWithUID("bltb6202sample73a1") 
BuiltQuery

BuiltQuery is used to retrieve objects of BuiltClass based on some condition. BuiltClass instance has method query, which, when executed, would retrieve objects of that class with specified condition.

//Obj-C
BuiltQuery *query = [projectClass query];

//Swift
var query:BuiltQuery = projectClass.query()
BuiltUpload

upload and uploadWithUID: method can be accessed on the BuiltApplication instance.

//Obj-C
BuiltUpload *uploadFile = [builtApplication upload];

//'bltb6202sample73a1' is dummy upload uid
BuiltUpload *existingUploadFile = [builtApplication uploadWithUID:@"bltb6202sample73a1"]; 

//Swift
var uploadFile:BuiltUpload = builtApplication.upload()

//'bltb6202sample73a1' is dummy upload uid
var existingUploadFile:BuiltUpload = builtApplication.uploadWithUID("bltb6202sample73a1") 
Cache Policies

There are a set of cache policies available for use. These policies are listed below.

ONLY_NETWORK (Default)

This is the default cache policy. It will always get the data from a network call.

CACHE_ELSE_NETWORK

This policy will try to first get the data from cache; on failure, it would make a network call.

NETWORK_ELSE_CACHE

This policy will try to make a network call; on failure, it would fetch it from cache.

CACHE_THEN_NETWORK

This policy would first get the data from cache. It would then make a network call to get the updated copy.

Cache policy can be set for particular query instance.

//Obj-C
BuiltQuery *query   = [projectClass query];
query.cachePolicy = CACHE_ELSE_NETWORK;

//Swift
var query:BuiltQuery = projectClass.query()
query.cachePolicy = CACHE_ELSE_NETWORK
ACL - Access Control List

The SDK provides some additional features that may be helpful for users. These features are explained below.

If you want to set permissions for BuiltObject, BuiltUpload, BuiltInstallation, and BuiltRole, it can be done using the BuiltACL class.

Let’s say, you want to set read permission for BuiltUpload for all users. You can do this by following the steps given below.

//Create an ACL object with the intended permission.
//Obj-C
BuiltACL *acl = [builtApplication acl];
[acl setPublicReadAccess:TRUE]; // set read permission for all.

//Swift
var acl:BuiltACL= builtApplication.acl();
acl.setPublicReadAccess(true) // set read permission for all.


//Create a BuiltUpload object and apply ACL to it.
//Obj-C
BuiltUpload *builtUpload = [builtApplication upload];
[builtUpload setACL:acl];   //Set acl object

//Swift
var builtUpload:BuiltUpload = builtApplication.upload();
builtUpload.ACL = acl; //Set acl object
Realtime

Several applications, such as chat, stock updates, alarm system, etc. require data to be fetched and pushed to and forth from the server in a matter of seconds. To support these requirements, Built.io Backend provides realtime functionality. In this, a socket connection is established between the client and the server, which enhances the speed of communication between the two.

Usage :

Create a BuiltApplication instance, which can be used for enabling realtime as shown below.

//'blt5d4sample2633b' is a dummy Application API key
//Obj-C

BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"blt5d4sample2633b"];
//to enable application to realtime
[builtApplication.enableRealtimeWithDelegate:self];

//Swift

var builtApplication:BuiltApplication = Built.applicationWithAPIKey("blt5d4sample2633b")
//to enable application to realtime
builtApplication.enableRealtimeWithDelegate(self)

The SDK provides some realtime connection delegates, which are helpful to determine the state of connection when realtime is being enabled.

Below mentioned all realtime delegate methods,

//'blt5d4sample2633b' is dummy Application API key
//ObjC - Realtime delegate methods

-(void)builtRealtimeApplicationWillConnect:(BuiltApplication*)builtApplication; {
    //When application is about to connect.
}

-(void)builtRealtimeApplicationDidConnect:(BuiltApplication*)builtApplication; {
    //When application is connected.
}

-(void)builtRealtimeApplicationWillDisconnect:(BuiltApplication*)builtApplication; {
    //When application is about to disconnect.
}

-(void)builtRealtimeApplicationDidDisconnect:(BuiltApplication*)builtApplication; {
    //When application is disconnected.
}

-(void)builtRealtimeApplication:(BuiltApplication*)builtApplication didReceivedError:(NSError*)error; {
    //When application receives any error in connection.
}

-(void)builtRealtimeApplicationWillReconnect:(BuiltApplication*)builtApplication; {
    //When application is trying to reconnect. 
    //After sucessful reconect attempt, builtRealtimeApplicationDidConnect: will get invoked.
}

//Swift - Realtime delegate methods

func builtRealtimeApplicationWillConnect(builtApplication: BuiltApplication!) {
    //When application is about to connect.
}

func builtRealtimeApplicationDidConnect(builtApplication: BuiltApplication!) {
    //When application is connected.    
}

func builtRealtimeApplicationWillDisconnect(builtApplication: BuiltApplication!) {
    //When application is about to disconnect.    
}

func builtRealtimeApplicationDidDisconnect(builtApplication: BuiltApplication!) {
    //When application is disconnected.    
}

func builtRealtimeApplication(builtApplication: BuiltApplication!, didReceivedError error: NSError!) {
    //When application receives any error in connection.
}

func builtRealtimeApplicationWillReconnect(builtApplication: BuiltApplication!) {
    //When application is trying to reconnect. 
    //After sucessful reconect attempt, builtRealtimeApplicationDidConnect: will get invoked.    
}   
Event Listener:

Built.io Backend uses events to notify the users when a particular action is performed. To listen to these events, we must first setup event listeners. The SDK provides several handy functions that help you manege the realtime functionality better. These functions are explained below in detail.

on

This function is available in BuiltApplication, BuiltClass, BuiltObject, BuiltUser and BuiltUpload classes. It takes two arguments: the event which we would like to listen to, and the callback to be invoked when the event is triggered. Below is an example where we set up a listener on an instance. Setting up a listener on instance requires read permission on it.

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

//Obj-C
BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"blt5d4sample2633b"];
BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
BuiltObject *projectObject = [projectClass object];
[projectObject on:BuiltRealtimeEventTypeCreate callback:^(id response, NSError *error) {
    if (error == nil) {
        //After new object is created in mentioned class this block will executed.
        //response object contains new created object
    }else {
        //error object contains more details if error occured while listening event.  
    }  
}];

//Swift
var builtApplication:BuiltApplication = Built.applicationWithAPIKey("blt5d4sample2633b")
var projectClass:BuiltClass = builtApplication.classWithUID("project")
var projectObject:BuiltObject = projectClass.object()
projectObject.on(BuiltRealtimeEventType.Create, callback: { (response, error) -> Void in
    if (error == nil) {
        //After new object is created in mentioned class this block will executed.
        //response object contains new created object
    }else {
        //error object contains more details if error occured while listening event.  
    }
})
off

As the name suggests, this method is used to stop a user from listening to event notifications.

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

//Obj-C
BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"blt5d4sample2633b"];
BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
BuiltObject *projectObject = [projectClass object];
//Listening for all new object creation in particular class.
[projectObject on:BuiltRealtimeEventTypeCreate callback:^(id response, NSError *error) {  
    //callback block
}];
//Listening for all update in objects in particular class.
[projectObject on:BuiltRealtimeEventTypeUpdate callback:^(id response, NSError *error) {  
    //callback block
}];

//Turning off update event for all update in objects in particular class.
[projectObject off:BuiltRealtimeEventTypeUpdate callback:^(id response, NSError *error) {  
    //callback block
}];

//Swift
var builtApplication:BuiltApplication = Built.applicationWithAPIKey("blt5d4sample2633b")
var projectClass:BuiltClass = builtApplication.classWithUID("project")
var projectObject:BuiltObject = projectClass.object()
//Listening for all new object creation in particular class.
projectObject.on(BuiltRealtimeEventType.Create, callback: { (response, error) -> Void in
    //callback block
})
//Listening for all update in objects in particular class.
projectObject.on(BuiltRealtimeEventType.Update, callback: { (response, error) -> Void in
    //callback block
})
//Turning off update event for all update in objects in particular class.
projectObject.off(BuiltRealtimeEventType.Update, callback: { (response, error) -> Void in
    //callback block
})
broadcast

Built.io Backend allows you to broadcast messages that could be listened by others by setting up listeners for it. Broadcast method should be used to broadcast message and is available on BuiltApplication, BuiltClass, BuiltObject, BuiltUser and BuiltUpload classes. Update permission is required on that instance to be able to broadbast a message. The example given below demonstrates the syntax.

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

//Obj-C
BuiltApplication *builtApplication = [Built applicationWithAPIKey:@"blt5d4sample2633b"];
BuiltClass *projectClass = [builtApplication classWithUID:@"project"];
//'bltb6202sample73a1' is dummy project uid
BuiltObject *projectObject = [projectClass objectWithUID:@"bltb6202sample73a1"];
//Listening on broadcast. 
[projectObject on:BuiltRealtimeEventTypeBroadcast callback:^(id response, NSError *error) {
    if (error == nil) {
        //response object contains broadcast message as string
    }else {
        //error object contains more details if error occured while listening event.  
    }  
}];

//Broadcasting message.
[projectObject broadcastWithMessage:@"Hi...!!!" callback:^(id response, NSError *error) {
    if (error == nil) {
        //response object contains broadcast message as string
    } else {
        //error objeect contains more details about error occured. 
    } 
}]

//Swift
var builtApplication:BuiltApplication = Built.applicationWithAPIKey("blt5d4sample2633b")
var projectClass:BuiltClass = builtApplication.classWithUID("project")
var projectObject:BuiltObject = projectClass.objectWithUID("bltb6202sample73a1")
//Listening on broadcast. 
projectObject.on(BuiltRealtimeEventType.Broadcast, callback: { (response, error) -> Void in
    if (error == nil) {
        //After new object is created in mentioned class this block will executed.
        //response object contains new created object
    }else {
        //error object contains more details if error occured while listening event.  
    }
})

//Broadcasting message.
projectObject.broadcastWithMessage("Hi...!!!", callback: { (response, error) -> Void in
    if (error == nil) {
        //After new object is created in mentioned class this block will executed.
        //response object contains new created object
    } else {
        //error objeect contains more details about error occured. 
    } 
})
Presence

This feature helps you determine if a certain application user is currently online or offline. It stores the “last seen” timestamp of the user, which is especially useful for chat applications. Additionally, it allows you to store a “status message” for your profile. Here is a list of some handy functions that will help you use the presence feature better.

Presence Operations

To get the logged-in user’s presence details, a combination of two methods will be used, i.e., ‘currentUser’ on BuiltApplication class and ‘presence’ on BuiltUser, which returns a BuiltUserPresence instance. If the users want to fetch the latest presence, then getPresence: method will make this task easier.

//Obj-C
BuiltUser *userObject = [builtApplication currentUser];
[userObject getPresence:^(NSError *error) {
    if (error == nil) {
        //fetched the user's presence successfully. to check use userObject.presence
    }else {
        //error while saving
    }
}];

//Swift
var userObject:BuiltUser = builtApplication.currentUser()
userObject.getPresence { (error) -> Void in
    if (error == nil) {
        //fetched the user's presence successfully. to check use userObject.presence
    }else {
        //error while saving
    }
}   

To get the presence details of some other application user, the SDK provides getPresence: method on BuiltUser instance. The below given example demonstrates the syntax.

// 'bltba9a44506dd9e741' is a uid of an object of inbuilt Application User class

//Obj-C
BuiltUser *userObject = [builtApplication userWithUID:@"bltba9a44506dd9e741"];
[userObject getPresence:^(NSError *error) {
    if (error == nil) {
        //fetched the user's presence successfully. to check use userObject.presence
    }else {
        //error while saving
    }
}];

//Swift
var userObject:BuiltUser = builtApplication.userWithUID("bltba9a44506dd9e741")
userObject.getPresence { (error) -> Void in
    if (error == nil) {
        //fetched the user's presence successfully. to check use userObject.presence
    }else {
        //error while saving
    }
}