Documentation : iOS References

Prelude

This document will provide you with detailed documentation about creating Mobeelizer client application on iOS platform.

If you want only a quick glimpse see tutorial instead.

In this document we assumes that you are familiar with:

  • Objective-C language
  • Basics of iOS application development (see iOS Dev Center)
  • Key concepts of Mobeelizer platform (see)

Configure your application

Attach necessary resources

To work with Mobeelizer platform first you have to download Mobeelizer SDK. Unpack downloaded file, make sure that root folder of unpacked SDK is named mobeelizer-ios-sdk.framework. Then in Xcode click on root of your project, find "Linked Frameworks and Libraries" section and press little "+" button. In window that opened hit "Add Other..." button. Choose root of downloaded SDK folder and press "Open". You should see mobeelizer-ios-sdk.framework added to your project and list in "Linked Frameworks and Libraries" section.

Also you need to attach sqlLite library to your project. Repeat steps above but instead of clicking "Add Other..." button find libsqlite3.0.dylib on the list and press "Add".

Next, download XML file of your application created in App Designer and put it in your project. If you use default setting then name of this file should be application.xml. You can use other name - but then you have to set definitionAsset property (see below)

Add Mobeelizer.plist file

In the next step you have to add Mobeelizer.plist file. Create it in your project. In this file you have to define some configuration properties:

NameRequired

Description

modeYES

There are three possible development modes:

  • development - application works off-line. Login and synchronization methods are mocked - they do nothing and returning no error. This mode allows you to develop client application completely separate from cloud deployment and management. Defining developmentRole parameter is necessary with this mode.
  • test - application will connect to test environment.
  • production - application will connect to production environment.
developmentRoleNO

This parameter is required only in 'development' mode - it is ignored on other modes.

Normally while login method system receives role of user. But as you can read above login method is off-line in development mode so you have to provide user role manually - as value of this parameter.

modelPrefixYES

Prefix of your model classes.

deviceYES

Name of device category. See this document for more explanation.

definitionAssetNO

Name of XML file with application definition. Default value is application.xml.

Initialize SDK

Open Application Delegate and add the messages for creating and destroying Mobeelizer.

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary*)launchOptions {
	// your code here
	[Mobeelizer create];
	return YES;
}

- (void)applicationWillTerminate:(UIApplication *)application {
	// your code here
	[Mobeelizer destroy];
}

Create models

Last thing to make for your application to work is to create models. For all the models that you have defined in App Deisigner and downloaded as XML files you have to create corresponding interface and implementation. While creating these elements you have to remember about few things:

  • Name

Should have prefix defined in modelPrefix property. Main part of name should be the same as name of corresponding model - but with first letter capitalized! Ex: When modelPrefix is "MOB" and model in App Center is named "product" then name of object should be MOBProduct.

  • Defining properties

In your @interface you have to define properties. You cannot use "copy" and "readonly" attributes! Remember about adding @synthesize in your @implementation!

  • Special properties

Every model class must have guid property and can have some optional special properties:

NameTypeRequired

Description

guidNSString*YES

Main object identifier

ownerNSString*NO

Information about owner of object

modifiedBOOLNO

This field will be YES if record was modified by user - but not synchronized yet.

conflictedBOOLNO

This field will be YES if object is conflicted. See here to read more about conflicts.

deletedBOOLNOTo delete entity set this field to true.
You should never set special properties value manually.
  • Model fields

Beside special fields you have to add property for every field defined in App Designer model. Name of these properties must be the same as name of model fields - but with lowercased first letter.

Type of properties must be one of listed below:

Model typeAvailable class properties types
belongs toNSString*
booleanNSNumber*, BOOL, Boolean, char
dateNSDate*, NSNumber*, NSInteger*, int, long
decimalNSDecimalNumber*, double, float
fileMobeelizerFile*
integerNSNumber*, int, short, long
textNSString*
Not required fields cannot be defined by primitive types like int or BOOL. Use Object types like NSInteger* and NSNumber* instead.

Log in to application

Before using any of Mobeelizer features you have to login the user to your cloud application. Any activity - like accessing database - before login will effect in throwing an error!

You can do that by calling one of login static methods from Mobeelizer object. There are four version of this method:

  • synchronous, with default environment name (see doc)
  • asynchronous, with default environment name (see doc)
  • synchronous, with environment name (see doc)
  • asynchronous, with environment name (see doc)

You have to remember, that when you log in any user for the first time your client application must be on-line (except 'development' mode.) Also first login can take long time to perform - because of initial synchronization processes that are automatically triggered after login verification. So better supply user with nice looking loading indicator. And remember - DO NOT call synchronous methods in main thread - you application will freeze.

Also you may wonder what is environment name. Firstly see this document to read about environments. As you can read there, on application creation two environments are created - one for test and one for production purpose. They are named accordingly "test" and "production". When you want to connect to these instances use default environment name method. But if you want to connect with environment manually created - you have to provide its name.

To change user you should use logout method. Remember to finish all background processes before calling it - logging out while synchronizationprocess can effect with unpredictable connector behavior!

Use database

Obtaining database object

Database can be accessed using object MobeelizerDatabase which can be obtained by calling method

MobeelizerDatabase *database = Mobeelizer.database;
Remember that to use database user have to be logged in.
You shouldn't connect to database directly without MobeelizerDatabase object! SDK will loose track of changes tracking and synchronize functionality will not work properly!

Basic operations

MobeelizerDatabase object allows you to easily perform basic database operations. Let say you have model product defined in MOBProduct.h.

Then you can write:

NSArray *allProducts = [database list:[MOBProduct class]];
NSUInteger count = [database count[MOBProduct class]];
MOBProduct *product = [database get:[MOBProduct class] withGuid:@"guidIdentifier"];
BOOL exists = [database exists:[MOBProduct class] withGuid:@"guidIdentifier"];

MOBProduct* product = // create product
MobeelizerErrors* errors = [database save:product];
if(errors != nil) {
	// notify the user about validation errors
}

[database remove:product];
[database remove:[MOBProduct class] withGuid:@"guidIdentifier"];

For more information see javadoc documentation.

Relations

To define relation you have to add 'belongs to' type field to model. Lets say you have models Order and OrderPosition. To connect these object with relation you have to add 'belongs to' field to OrderPosition - lets name it Order.

As you can read above 'belongs to' type has to be mapped as NSString* field. This field will contain identifier of related object. So you can write:

// ------- create new order with positions
MOBOrder *order = [[MOBOrder alloc] init];

// fill order fields
MobeelizerErrors *orderSaveErrors = [database save:order];
MOBOrderPosition *position = [[MOBOrderPosition alloc] init];

// fill position fields
position.order = order.guid;
MobeelizerErrors *positionSaveErrors = [database save:position];

// ------- get order of position:
MOBOrderPosition *position = [database get:[MOBOrderPosition class] withGuid:@"positionIdentifier"];
MOBOrder *order = [database get:[MOBOrder class] withGuid:position.order];

Files

All binary data are wrapped inside MobeelizerFile object. Lets assume that you have OrderWithAttachment object. And it have attachment field of 'file' type. Then you can access content of file by coding:

MOBOrderWithAttachment *order = [database get:[MOBOrderWithAttachment class] withGuid:@"orderIdentifier"];
MobeelizerFile *attachment = order.attachment;
NSString *attachmentIdentifier = attachment.guid;
NSString *attachmentName = attachment.name;
NSData *content = attachment.data;

To create new MobeelizerFile instance you can:

// ------- create new file...
NSData *content = // get file content
MobeelizerFile *newAttachment = [Mobeelizer createFile:@"newAttachmentName" withData:content];

// ------- ...or use existing one
MobeelizerFile newAttachment = [Mobeelizer createFile:@"newAttachmentName" withGuid:@"existingAtachmentGuid"];

Remember about changing order file field:

OrderWithAttachment *order = // get object from database or create new one
order.attachment = newAttachment;
MobeelizerErrors *orderSaveErrors = [database save:order];

Advanced database queries

Advanced queries can be accessed by MobeelizerCriteriaBuilder class.To get criteria object just call method:

MobeelizerCriteriaBuilder *query = [database find:[MOBProduct class]];

Next define your query (see below). After that you can:

// get list of objects meeting query conditions
NSArray* list = [query list];

// get number of objects meeting query conditions
NSUInteger count = [query count];

// get single object meeting query conditions
MOBProduct *product = [query uniqueResult];

While creating query you can:

  • Limit result objects number:
[query maxResults:10];
  • Set the first result
[query firstResult:5 maxResults:10];
  • Add order
[query addOrder:[MobeelizerOrder asc:@"name"]]; // order ascending by name field
[query addOrder:[MobeelizerOrder desc:@"price"]]; // order descending by price field
  • Add restrictions
[query add:[MobeelizerCriterion field:@"name" eq:@"table"]] // name equals "table"
[query add:[MobeelizerCriterion or:
	[MobeelizerCriterion field:@"price"between:10 and:20],
	[MobeelizerCriterion fieldIsNull:@"price"], nil]
]; // price between 10 and 20 or no price at all

For more informations about restrictions see MobeelizerCriterion reference.

You can also combine many elements to create more complicated queries:

// Get products with price less than 100 order from cheaper to more expensive.
// Products with same price order alphabetically.
// Display page 3 of results (10 results on page).
NSArray *products = [[[[[[[database find:[MOBProduct class]]
	add:[MobeelizerCriterion field:@"price" le:100]]
	addOrder:[MobeelizerOrder desc:@"price"]]
	addOrder:[MobeelizerOrder asc:@"name"]]
	firstResult:20 maxResults:10]
list];

For more information see MobeelizerCriteriaBuilder reference.

Synchronize data

Synchronizing data with cloud cannot be easier! Just call one of sync methods on Mobeelizer object.

Normal synchronization

To perform data synchronization call sync method (or it's asynchronous version).

Synchronization process can take long time, so if you want to block application on this time - better supply user with nice-looking loading indicator. And remember - DO NOT call synchronous method in main thread - you application will freeze.

Full synchronization

Full synchronization is a process which removes all data and downloads from Mobeelizer Cloud. It is triggered automatically when user logs in for the first time - but you can call it manually. Just call syncAll method (or asynchronous version).

You should block all user actions for this process (database will be erased). And once again remember about not calling synchronous method in main thread.

In full synchronization process user-modified data is not send to cloud, so all not synchronized data (with modified flag) will be lost! To prevent this perform normal synchronization before.

Sync status listener

You can register listener for all notifications about sync status changes. To do it create class realizing MobeelizerSyncListener protocol. Then register it for sync event using registerSyncStatusListener method.

See MobeelizerSyncListener reference for more information about available sync statuses.

Push notifications

To learn about Push notification see Push notifications key concept page.

Push notifications on iOS devices are provided by Apple Push Notification Service (APNs). Basic knowledge of it's mechanisms are necessary to understand following reference documentation.

Configuring application

  • Create push certificates

Go to iOS Dev Center, log in, then go to the iOS Provisioning Portal page (there's a link in the upper right). Go to App Id's section and follow these instructions to create Push SSL Certificate (both Development and Production).

  • Configure application in App Designer

In App Designer in 'Create' mode click "Push notifications" button on the left. There you can configure your application for push notifications by uploading certificates and provide it's passwords.

Test certificate will be used on test environments, production on production ones.

Registering to receive push notifications

If you want iOS device to be able to receive push notifications you must follow instructions from iOS Developer Library. Also you have to send registration token to Mobeelizer server by calling method:

[Mobeelizer registerForRemoteNotificationsWithDeviceToken:pushToken];

Below we provide you with more detailed steps to configure your application:

  • Modify application delegate

To register and handle Push Notifications modify AppDelegate implementation:

@implementation MDAppDelegate
@synthesize window = _window;

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
        [Mobeelizer create];
        [[UIApplication sharedApplication] registerForRemoteNotificationTypes:UIRemoteNotificationTypeAlert];
        return YES;
}

- (void)applicationWillTerminate:(UIApplication *)application {
        [Mobeelizer destroy];
}

- (void)application:(UIApplication *)app didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)token {
        [Mobeelizer registerForRemoteNotificationsWithDeviceToken:token];
}

- (void)application:(UIApplication *)app didFailToRegisterForRemoteNotificationsWithError:(NSError *)err {
        NSLog(@"Error in registration. Error: %@", err);
}

- (void)application:(UIApplication *)app didReceiveRemoteNotification:(NSDictionary *)userInfo {
        // handle message receiving
}

@end

To unregister your application from receiving push navigation just call:

[Mobeelizer unregisterForRemoteNotifications];

Sending push notification

To send Push notification call one of methods on Mobeelizer object: