iOS Application: implementation tips
1. API calls to make from the iOS application (using the Apstrata iOS client SDK)
Note: most of the methods exposed by the iOS client SDK to invoke Apstrata's APIs gather the required parameters into an instance of
NSDictionary. In the below, we use the following convention to represent the content of this dictionary:
{ "key1" : "value1", "key2" : "value2" } : a dictionary containing two key/value pairs
{ }: stands for an empty NSDictionary.
1.a. To retrieve the list of available concerts
Use one of the following methods of the iOS client SDK:
- callAPIJson (NSString*) methodName params:(NSDictionary *)params files:(NSDictionary *)files
(returns the result in JSON format)
- callAPIMethod:(NSString*) methodName parameters:(NSDictionary *)params files:(NSDictionary *) files
(returns the result in XML format),
with the following parameters values:
- methodName: "Query"
- params: { "apsdb.query" : "apsdb.schema = \"concert\" ", "apsdb.queryFields" : "title, ticketPriceLL, picture, description, date,
- apsdb.documentKey" }
- files: { }
should add the following to the params dictionary: [..., ("apsdb.count", "true"), ("apsdb.resultsPerPage", "some_number"),
("apsdb.pageNumber", "the_page_number")]
1.b. To retrieve the URL of the picture
The above query returns the name of the picture file in the "picture" field, therefore:
Use the following method of the iOS client SDK to retrieve the URL of the picture file:
- getFullApiUrl(NSString* action ) methodparameters: (NSDictionary *) parameters files: (NSDictionary *) files;
or the method hereafter to actually download the file (if "path" is an empty string or null, then the method returns a non null NSData object
filled with the file content:
- callAPIFile:(NSString *)methodName params:(NSDictionary *)params path:(NSString *)path
Example of code for retrieving the URL of a picture (the "client" object below is an instance of the Apstrata iOS client):
// The API name that allows to retrieve a file NSString *methodName = @"GetFile"; // The name of the image file NSString *fileName = @"Ixia.gif"; // The parameters to send along the call to GetFile NSMutableDictionary *parameters = [[NSMutableDictionary alloc] init]; [parameters setObject: @"documentWithFile" forKey: @"apsdb.documentKey"]; [parameters setObject: fileName forKey: @"apsdb.fileName"]; [parameters setObject: @"apsdb_attachments" forKey: @"apsdb.fieldName"]; // Get the image URL by call getFullApiUrl on the iOS Client instance NSString* imageUrl = [client getFullApiUrl:methodName parameters: parameters files:files];
Example of code to download a file and store it locally
// GetFile is the Apstrata API to invoke methodName = @"GetFile"; // Specify the path where to download the file NSString *path = @"/Users/elementn/Library/Application Support/iPhone simulator/receivedFiles/"; NSString *fileName = @"textfile.txt"; path = [path stringByAppendingString: fileName]; // Prepare the parameters of the call, i.e. the document key that contains the file to download, the file name and the name // of the document field to which the file is attached [parameters setObject: @"documentWithFile" forKey: @"apsdb.documentKey"]; [parameters setObject: fileName forKey: @"apsdb.fileName"]; [parameters setObject: @"apsdb_attachments" forKey: @"apsdb.fieldName"]; // Invoke the "GetFile" API from the iOS client SDK [client callAPIFile: methodName params:parameters path:path]; NSFileManager *fileManager = [NSFileManager defaultManager]; bool fileWasUploaded = [fileManager fileExistsAtPath:path] == YES; if (fileWasUploaded) NSLog(@"File was successfully uploaded); else NSLog(@"File was not successfully uploaded");
the demo application, all documents have a schema and the name of the field used to attach files (images) is "picture".
1.c. To buy tickets
Use
callAPIJson (returns the result in JSON format) or callAPIMethod:(NSString*) methodName parameters:(NSDictionary *)params files:(NSDictionary *) files
in the iOS SDK (returns the result in JSon), with the following parameters values:
- methodName: "RunScript"
- params: { "apsdb.scriptName": "app.buyTickets", "amount: "some_amount", "quantity" : "some_qty", "concertTitle" : "the_title","name" : "buyer's_name", "msisdn" : "the_phone_number" }
- files: { }
1.d. To retrieve the picture gallery of a given concert
Use
callAPIJson (returns the result in JSON format) or callAPIMethod:(NSString*) methodName parameters:(NSDictionary *)params files:(NSDictionary *) files
in the iOS SDK (returns the result in Json), with the following parameters values:
- methodName: "Query"
- params: { "apsdb.query" : "concert= \"the_key_of_the_concert_document\" ", "apsdb.queryFields" : "picture" }
- files: { }
there are images.
1.e. To upload an image to the gallery
Use
callAPIMethod:(NSString*) methodName parameters:(NSDictionary *)params files:(NSDictionary *) files
in the iOS SDK (returns the result in XML), with the following parameters values:
methodName: "SaveDocument"
- params: { "apsdb.schema" : "concert_image", "concert" : "the_key_of_the_concert_document", "title" : "the_title_of_the_img", "description" : "some_description", "tags" : "tag1,tag2,etc" }
- files: { a dictionary of key/NamedFileData instances, see example of code below }
- files: { a dictionary of key/NamedFileData instances, see example of code below }
Example of Objective C code to upload files using the iOS SDK:
// save document with attached image file NSString* methodName = @"SaveDocument"; // Create the parameters dictionary NSMutableDictionary *parameters = [[NSMutableDictionary alloc] init]; // Add the document key to the parameters dictionary [parameters setObject: @"documentWithFile" forKey: @"apsdb.documentKey"]; // Create an instance of NameFileData that will contain the image file NamedFileData* namedFileDataImg = [[NamedFileData alloc] init]; // Load the image file from some folder UIImage *fileImage = [[UIImage alloc] initWithContentsOfFile:@"/Users/elementn/Library/Application Support/iPhone simulator/Ixia.gif"]; // Load the image bytes into an NSData instance and specify a name for the file NSData *fileData = [NSData dataWithData: UIImagePNGRepresentation(fileImage)]; [namedFileDataImg setFileData:fileData]; [namedFileDataImg setFileName:@"Ixia.gif"]; // Create an array of NamedFileInstances that will contain the files to upload NSMutableArray* fileDataArray = [NSMutableArray arrayWithObject:namedFileDataImg]; // Add a new element to the files parameters and associate the file to upload to the "apsdb_attachments" field of the targeted apstrata document [files setValue: fileDataArray forKey:@"apsdb_attachments"]; // Call the SaveDocument API through the iOS SDK result = [client callAPIMethod:methodName parameters:parameters files:files]; NSLog(@"Apstrata's Response: %@",result);
1.f. To tweet
Tweeting is a twofold process:
1) first, you need to authorize the touch twitter application on your twitter account, unless the user has already authorized the application
2) second, the mobile application invokes Apstrata to tweet
1) In order to authorize the touch twitter application:
Use
callAPIJson (returns the result in JSON format) or callAPIMethod:(NSString*) methodName parameters:(NSDictionary *)params files:(NSDictionary *) files
in the iOS SDK (returns the result in Json), with the following parameters values:
- methodName: "RunScript"
- params: { "apsdb.scriptName": "social.twitter.integrate", "command" : "getRequestToken", "requester": "the_phone_number"}
- files: { }
This method returns a Json object containing two properties: "accessToken" and "accessSecret". These need to be used in the second step (tweeting).
contains a token and token secret field for every authorized twitter application for the given phone number (respectively
"token_consumerkey" and "secret_consumerkey"). You can use this document after authorizing the application the first time, in order to
avoid another unnecessary authorization.
2) In order to tweet on the user's twitter account:
Use
callAPIJson (returns the result in JSON format) or callAPIMethod:(NSString*) methodName parameters:(NSDictionary *)params files:(NSDictionary *) files
in the iOS SDK (returns the result in Json), with the following parameters values:
- methodName: "RunScript"
- params: { "apsdb.scriptName": "social.twitter.api", "consumerKey": "VZSaDoqSgDSzAOQjnnDhw", "consumerSecret": "nUjEPLTwaAiWjFgC5x6SrilI4yW86Fy6RnI0V3o", "accessToken": "The_access_token_obtained_at_step_1", "accessTokenSecret": "The_access_token_secret_obtained_at_step_1", "tweetString": "Some_message", "command": "tweet" }
- files: { }
1.g. To retrieve the twitter authentication token and twitter authentication token secret for tweeting (if needed)
Use
callAPIJson (returns the result in JSON format) or callAPIMethod:(NSString*) methodName parameters:(NSDictionary *)params files:(NSDictionary *) files
in the iOS SDK (returns the result in XML), with the following parameters values:
- methodName: "Query"
- params: { "apsdb.query" : "apsdb.documentKey= \"twitter_the_phone_number\" ", "apsdb.queryFields" : "token_VZSaDoqSgDSzAOQjnnDhw, secret_VZSaDoqSgDSzAOQjnnDhw" }
- files: { }
2. Making calls to Apstrata
Use your account authentication key and secret
The URL to the Apstrata cluster is : https://apstrata.touch.com/apsdb/rest
The below example shows how to create an instance of the Apstrata iOS client that allows invoking services on the above mentioned
account:
// Properties of the account and cluster NSString *url = @"https://apstrata.touch.com/apsdb/rest"; NSString *authKey = @"your_auth_key_here"; NSString *secret = @"your_secret_here"; // Create an instance of the Apstrata iOS client. We use the SIMPLE authentication mechanism ApstrataiPhoneClient *client = [[ApstrataiPhoneClient alloc] initWithURL: url key: authKey secret: secret authMode: SIMPLE];
3. Schemas
We use the following schema (schemas will not be directly used by the iOS application):
concert, concert_ticket, concert_image, billing_transaction