- Configure your application
- Create models
- Log in to application
- Use database
- Synchronize data
- Push notifications
This document will provide you with detailed documentation about creating Mobeelizer client application on iOS platform.
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)
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:
There are three possible development modes:
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.
Prefix of your model classes.
Name of device category. See this document for more explanation.
Name of XML file with application definition. Default value is application.xml.
Open Application Delegate and add the messages for creating and destroying Mobeelizer.
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:
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:
Main object identifier
Information about owner of object
This field will be YES if record was modified by user - but not synchronized yet.
This field will be YES if object is conflicted. See here to read more about conflicts.
|deleted||BOOL||NO||To delete entity set this field to true.|
- 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 type||Available class properties types|
|boolean||NSNumber*, BOOL, Boolean, char|
|date||NSDate*, NSNumber*, NSInteger*, int, long|
|decimal||NSDecimalNumber*, double, float|
|integer||NSNumber*, int, short, long|
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!
Obtaining database object
Database can be accessed using object MobeelizerDatabase which can be obtained by calling method
MobeelizerDatabase object allows you to easily perform basic database operations. Let say you have model product defined in MOBProduct.h.
Then you can write:
For more information see javadoc documentation.
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:
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:
To create new MobeelizerFile instance you can:
Remember about changing order file field:
Advanced database queries
Advanced queries can be accessed by MobeelizerCriteriaBuilder class.To get criteria object just call method:
Next define your query (see below). After that you can:
While creating query you can:
- Limit result objects number:
- Set the first result
- Add order
- Add restrictions
For more informations about restrictions see MobeelizerCriterion reference.
You can also combine many elements to create more complicated queries:
For more information see MobeelizerCriteriaBuilder reference.
Synchronizing data with cloud cannot be easier! Just call one of sync methods on Mobeelizer object.
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 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.
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.
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.
- 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.
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:
Below we provide you with more detailed steps to configure your application:
- Modify application delegate
To register and handle Push Notifications modify AppDelegate implementation:
To unregister your application from receiving push navigation just call:
Sending push notification
To send Push notification call one of methods on Mobeelizer object:
- sendRemoteNotification:(NSDictionary *)notification;
- sendRemoteNotification:(NSDictionary *)notification toDevice:(NSString *)device;
- sendRemoteNotification:(NSDictionary *)notification toUsers:(NSArray *)users;
- sendRemoteNotification:(NSDictionary *)notification toUsers:(NSArray *)users onDevice:(NSString *)device;
- sendRemoteNotification:(NSDictionary *)notification toGroup:(NSString *)group;
- sendRemoteNotification:(NSDictionary *)notification toGroup:(NSString *)group onDevice:(NSString *)device;