{"_id":"56c2aadf46d27917009d0719","githubsync":"","version":{"_id":"56bc8e689afb8b0d00d62dd2","project":"56bc8e679afb8b0d00d62dcf","__v":18,"createdAt":"2016-02-11T13:36:40.146Z","releaseDate":"2016-02-11T13:36:40.146Z","categories":["56bc8e689afb8b0d00d62dd3","56c3c837bc41330d009f25ed","56c3c83e521f350d00d348eb","56c3c8452d97560d00e23cd8","56c3c85234df460d00c2beb8","56c4180d70187b17005f43b4","56c418162d97560d00e23cf6","56c4181cc4796b0d007ef039","56c4182370187b17005f43b5","56c418292e75e01700986052","56c4183328bd680d005e7ac6","56c4183bbb64720d00552b88","56c418414040602b0064cea0","56c4184754b6030d00ec29a1","56c4184c28bd680d005e7ac7","56c4185370187b17005f43b6","56c4185b6063071700500cfc","582a98b6f8c0a0190053d7a5"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"category":{"_id":"56bc8e689afb8b0d00d62dd3","__v":6,"pages":["56bc8e699afb8b0d00d62dd5","56c2aadf46d27917009d0719","56c2bc123e1b8d2300fe4ca0","56c2bc1dde695a19009a4aa7","56c2bc2a46d27917009d0722","56c2bc398073830d00e42e6f"],"project":"56bc8e679afb8b0d00d62dcf","version":"56bc8e689afb8b0d00d62dd2","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2016-02-11T13:36:40.802Z","from_sync":false,"order":0,"slug":"documentation","title":"Getting Started"},"user":"56b98db7bb36440d0001f492","project":"56bc8e679afb8b0d00d62dcf","parentDoc":null,"__v":53,"updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-16T04:51:43.168Z","link_external":false,"link_url":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":7,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overview\"\n}\n[/block]\nThe Buddy iOS SDK helps you get up and running in seconds.\n\nFor the most part, the Buddy iOS SDK takes care of all the housekeeping of making requests against the Buddy REST API:\n\n  * Building and formatting requests\n  * Managing authentication\n  * Parsing responses\n  * Loading and saving credentials \n\nWith that handled, all you have to do is initialize the SDK and start making some calls!\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Getting Started\"\n}\n[/block]\nTo get started with the Buddy Platform SDK, please reference the Getting Started series of documents at [Intro To Buddy](doc:intro-to-buddy). You will need an App ID and Key before you can use the SDK. The Getting Started documents will walk you through obtaining everything you need and show you where to find the SDK for your platform.\n\nApplication IDs and Keys are obtained at the Buddy Developer Dashboard at [buddyplatform.com](https://buddyplatform.com).\n\nFull documentation for Buddy's services are available at [docs.buddy.com](https://docs.buddy.com).\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Installing the SDK\"\n}\n[/block]\n## Prerequisites\n\n  * iOS 6.0 or greater\n  * Xcode 6.4 or greater \n\nThe Buddy iOS SDK can be accessed via [Cocoapods](http://cocoapods.org/). Cocoapods version of at least 0.39.0 is required to install the Buddy SDK and sample apps.\n\n## Install with Cocoapods\n\nWe highly recommend using Cocoapods to install the Buddy SDK. It's fast and makes it much easier to keep up to date with the latest SDK release. If you're new to Cocoapods, see install instructions [here](https://guides.cocoapods.org/using/getting-started.html). Cocoapods depends on Ruby, and depending on your Ruby version the Cocoapods installer may give you trouble; you may need to upgrade Ruby (we recommend using [RVM](https://rvm.io)). (For more Cocoapods troubleshooting steps see [here](https://guides.cocoapods.org/using/troubleshooting#installing-cocoapods)).\n\n#### To create a new project using the Buddy SDK:\n\n1\\.  Create a new Xcode project.\n\n2\\.  In a Terminal window run:\n\n```\ncd <project-dir>\n```\n\n3\\. Create a Podfile:\n\n```\ntouch Podfile\n```\n\n4\\. Open the file with your favorite editor and add:\n\n```\nplatform :ios, '6.0'\ntarget '<project name>' do\n    pod 'BuddySDK'\nend\n```\n<project name> should be the name of your Xcode project.\n\n5\\. If you created a Swift-based project, add:\n\n```\nuse_frameworks!\n```\n\n6\\. Save the Podfile.\n\n7\\. In your Terminal window run:\n\n```\npod install\n```\n\n8\\. **In Xcode open the just-generated `.xcworkspace` file for your project (not the `.xcodeproj` file).**\n\n#### To integrate the Buddy SDK into an existing project:\n\n1\\. In a Terminal window run:\n\n```\ncd <project-dir>\n```\n\n2\\. Create a Podfile:\n\n```\ntouch Podfile\n```\n\n3\\. Open the file with your favorite editor and add:\n\n```\nplatform :ios, '6.0'\ntarget '<project name>' do\n    pod 'BuddySDK'\nend\n```\n<project name> should be the name of your Xcode project.\n\n4\\. If your project is Swift-based, add:\n\n```\nuse_frameworks!\n```\n\n5\\. Integrating CocoaPods with an existing workspace requires one extra line in your Podfile. Simply specify the relative path and `.xcworkspace` root filename like so:\n\n```\nworkspace '../MyWorkspace.xcworkspace'\n```\n\n6\\. Save the Podfile.\n\n7\\. Make sure your workspace is closed in Xcode. Then in your Terminal window run:\n\n```\npod install\n```\n\n8\\. **Re-open your `.xcworkspace` file in Xcode.**\n\n## Install from Source\n\nBuddy hosts our SDK source on GitHub. To access it, you need to have a GitHub account, and you will also need [Git](http://git-scm.com/download) installed. If you'd like to contribute SDK modifications or additions to Buddy, you'll want to [fork the repository](https://help.github.com/articles/fork-a-repo) so you can issue [pull requests](https://help.github.com/articles/be-social#pull-requests). See the \"Contributing Back\" section below for details.\n\n1\\. In a Terminal window run:\n\n```\ngit clone https://github.com/BuddyPlatform/Buddy-iOS-SDK.git\n```\n\nThis will clone the latest version of the SDK into a directory called **Buddy-iOS-SDK.**\n\n2\\. Navigate to the **Buddy-iOS-SDK** directory that was created when you cloned the Buddy GitHub repository.\n\nThe iOS source is in the **Buddy-iOS-SDK\\Src** directory.\n\n#### Build the GitHub Source\n\nTo reference the local SDK in your project:\n\n1\\. Follow the \"Install with Cocoapods\" steps above to create a Podfile.\n\n2\\. You must add a `:path` parameter to your Podfile to indicate the relative path from your project to the Buddy SDK. It should look something like this:\n\n```\nplatform :ios, '6.0'\ntarget '<project name>' do\n    pod 'BuddySDK', :path => '../../BuddySDK.podspec'\nend\n```\n<project name> should be the name of your Xcode project.\n\n3\\. Then in your Terminal window run the following. It's ok to do this again if you have already done it:\n\n```\npod install\n```\n\nNow any changes you make to the local Buddy SDK source will be picked up by your project when you build it in Xcode. If you add or remove files to the Buddy SDK, you will need to do a `pod update` for your project in a Terminal window.\n\n# Using the iOS SDK\n\nVisit the [Buddy Dashboard](https://buddyplatform.com/) to obtain an application ID and key, which are needed for your app to communicate with Buddy.\n\nBoth Objective-C and Swift-based projects are supported.\n\n## Initialize the SDK\n\nTo reference the Buddy SDK in your source file, you need to put an import keyword at the top of the file that contains your AppDelegate:\n\nObjective-C: Open the `AppDelegate.m` file and import the BuddySDK:\nSwift: Open the `AppDelegate.swift` and import the BuddySDK:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"#import \\\"BuddySDK/Buddy.h\\\"\",\n      \"language\": \"objectivec\"\n    },\n    {\n      \"code\": \"import BuddySDK\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\nBefore you can call any methods in the SDK, it must be initialized. The best place to do this is inside your `AppDelegate.` Initialize your client in the `didFinishLaunchingWithOptions` method:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[Buddy init::::at:::\\\"YOUR_APP_ID\\\" appKey:@\\\"YOUR_APP_KEY\\\"];\",\n      \"language\": \"objectivec\"\n    },\n    {\n      \"code\": \"Buddy.init(\\\"YOUR_APP_ID\\\", appKey: \\\"YOUR_APP_KEY\\\");\",\n      \"language\": \"swift\"\n    }\n  ]\n}\n[/block]\nReplace \"YOUR_APP_ID\" and \"YOUR_APP_KEY\" above with your Buddy app's ID and key from the [Buddy Dashboard.](https://buddyplatform.com/)\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Example Objective C Calls\",\n  \"sidebar\": true\n}\n[/block]\nThe Buddy iOS SDK handles user creation, login, and logout. Here are some example Objective C calls.\n\n## Create A User\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[Buddy createUser:self.signupUsername.text\\n       password:self.signupPassword.text\\n       firstName:self.signupFirstName.text\\n       lastName:self.signupLastName.text\\n       email:self.signupEmail.text\\n       dateOfBirth:nil \\n       gender:nil \\n       tag:nil \\n       callback:^(id newBuddyObject, NSError *error)\\n{\\n  if (!error)\\n  {\\n    // Greet the user\\n  }\\n}];\",\n      \"language\": \"objectivec\",\n      \"name\": \"\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n\n[block:textarea]\n{\n  \"text\": \"## User Login\",\n  \"sidebar\": true\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[Buddy loginUser:@\\\"username\\\" password:@\\\"password\\\" callback:^(id newBuddyObject, NSError *error)\\n{\\n  if (!error)\\n  {\\n    // Greet the user\\n  }\\n}];\",\n      \"language\": \"objectivec\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n\n[block:textarea]\n{\n  \"text\": \"## User Logout\",\n  \"sidebar\": true\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"[Buddy logoutUser:^(NSError *error) {\\n    // Perform some action on logout\\n}];\",\n      \"language\": \"objectivec\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n## User Authorization Selector\n\nYou can implement a selector named `authorizationNeedsUserLogin` on your AppDelegate that gets called whenever a Buddy call is made that requires a logged-in user. That way, you won't have to manage user login state. Here's an example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"-(void)authorizationNeedsUserLogin\\n{    \\n    // To ensure that login UI is not shown twice if the selector is called multiple times\\n    if (self.loginPresented == TRUE)\\n    {\\n        return;\\n    }\\n    self.loginPresented = TRUE;\\n\\n    LoginViewController *loginVC = [[LoginViewController alloc]\\n                                initWithNibName:@\\\"LoginViewController\\\" bundle:nil];\\n\\n   [self.navController.topViewController presentViewController:loginVC animated:NO completion:nil];\\n}\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n## REST Interface\n\nEach SDK provides wrappers that make REST calls to Buddy. Responses can be handled in two ways: you can create your own wrapper classes, similar to those found in the `Models` folder, or you can use a basic `[NSDictionary class]`.\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"POST\"\n}\n[/block]\nIn this example we'll create a checkin. Take a look at [Create Checkin](doc:create-checkin) then:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"BPCoordinate *coord = BPCoordinateMake(47.1, -121.292);\\n\\nNSDictionary *params = @{@\\\"location\\\": coord,\\n                         @\\\"comment\\\": @\\\"A comment about this awesome place!\\\"};\\n\\n[Buddy POST:@\\\"/checkins\\\" parameters:params class:[NSDictionary class] callback:^(id checkin, NSError *error) {\\n    if (!error) {\\n      NSLog(@\\\"Checkin post went as planned\\\");\\n    } else {\\n      NSLog(@\\\"%@\\\", error);\\n    }\\n}];\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"GET\"\n}\n[/block]\nWe now can call GET to search for the checkin we just created!\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"BPCoordinateRange *range = BPCoordinateRangeMake(47.1, -121.292, 2500);\\n\\nNSDictionary *params = @{@\\\"locationRange\\\": range};\\n\\n[Buddy GET:@\\\"/checkins\\\" parameters:params class:[BPPageResults class] callback:^(id results, NSError *error) {\\n    if (!error) {\\n      NSArray *checkins = [(BPPageResults*)results convertPageResultsToType:[BPCheckin class] ];\\n      NSLog(@\\\"%@\\\", checkins); // Log or do something with the response\\n    } else {\\n      NSLog(@\\\"GET checkins was unsuccessful.\\\");\\n      NSLog(@\\\"%@\\\", error);\\n    }\\n}];\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\nIf we wanted to search for the specific checkin, by ID, we can do that too:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"NSString* path = [NSString stringWithFormat:@\\\"/checkins/%@\\\", checkinId];\\n[Buddy GET:path parameters:nil class:[BPCheckin class] callback:^(id checkin, NSError *error) {\\n    if (!error) {\\n      BPCheckin *checkin = (BPCheckin*)checkin;\\n      // do something with the response\\n    } else {\\n      NSLog(@\\\"GET checkin was unsuccessful.\\\");\\n      NSLog(@\\\"%@\\\", error);\\n    }\\n}];\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"PUT/PATCH/DELETE\"\n}\n[/block]\nEach remaining REST verb is available through the Buddy SDK using the same pattern as the POST example.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Working With Files\"\n}\n[/block]\nBuddy offers support for binary files. The iOS SDK works with files through our REST interface similarly to other API calls. The key class is `BPFile`, which is a wrapper around NSData along with a MIME content type.\n\n**Note:** Responses for files deviate from the standard Buddy response templates. See the [Buddy Platform documentation](https://docs.buddy.com) for more information.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Upload A File\"\n}\n[/block]\nHere we demonstrate uploading a picture. All binary files use the same pattern with a different path and different parameters. To upload a picture POST to `\"/pictures\"`:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"BPFile *file = [[BPFile alloc] init];\\nfile.contentType = @\\\"image/jpg\\\";\\nfile.fileData = UIImageJPEGRepresentation(koi, .75);\\n\\nNSDictionary *parameters = @{@\\\"data\\\": file,\\n                             @\\\"caption\\\": @\\\"Koi are awesome fish.\\\"};\\n\\n[Buddy POST:@\\\"/pictures\\\" parameters:parameters class:[NSDictionary class] callback:^(id picture, NSError *error) {\\n    if (!error) {\\n      NSLog(@\\\"Image uploaded successfully\\\");\\n    } else {\\n      NSLog(@\\\"Image upload went wrong\\\");\\n      NSLog(@\\\"%@\\\", error);\\n    }\\n}];\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Download A File\"\n}\n[/block]\nTo download a file send a GET request with BPFile as the operation type. This sample downloads the picture we uploaded in the \"Upload File\" example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"// Don't forget to store the picture ID in pictureId!\\n\\n[Buddy GET:[NSString stringWithFormat:@\\\"/pictures/%@/file\\\", pictureId] parameters:nil class:[BPFile class] callback:^(id obj, NSError *error) {     \\n    if (!error)\\n    {\\n      BPFile *file = (BPFile*)obj;\\n\\n      UIImage* image = [UIImage imageWithData:file.fileData];\\n      // Do something with the image!\\n\\n      NSLog(@\\\"Image download successful\\\");\\n    } else {\\n      NSLog(@\\\"Something went wrong\\\");\\n    }\\n\\n}];\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Advanced Usage\"\n}\n[/block]\n## Automatically report location for each Buddy call\n\nIf you set the current location in the Buddy client, each time a Buddy call is made that location will be passed in the call. Most calls that send data to Buddy have a location parameter; if a call is made that doesn't take location, the parameter will be ignored.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"BPCoordinate *location = BPCoordinateMake(47.1, -121.292);\\n\\n[Buddy setLastLocation: location];\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n## Multiple concurrent users\n\nIf you need to have multiple clients (for example if you need to interact with multiple users concurrently from your app), you can capture clients created from `Buddy.init` and use those clients individually:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"id<BuddyClientProtocol> client1 = [Buddy init:@\\\"Your App ID 1\\\" appKey:@\\\"Your App Key1\\\"];\\n\\nid<BuddyClientProtocol> client2 = [Buddy init:@\\\"Your App ID 2\\\" appKey:@\\\"Your App Key2\\\"];\\n\\n[client1 loginUser:@\\\"user1\\\" password:@\\\"password1\\\" callback:<#^(id newBuddyObject, NSError *error)callback#>\\n{\\n     if (!error)\\n     {\\n         // Greet user1\\n     }\\n}];\\n\\n[client2 loginUser:@\\\"user2\\\" password:@\\\"password2\\\" callback:<#^(id newBuddyObject, NSError *error)callback#>\\n {\\n     if (!error)\\n     {\\n         // Greet user2\\n     }\\n }];\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n## Handling connectivity\n\nYou can implement a selector named `connectivityChanged` on your AppDelegate if you would like to be notified if your device loses and regains ability to communicate to the Buddy servers for whatever reason. Here's an example that notifies the user:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"- (void)connectivityChanged:(NSNumber *)level\\n{\\n    BPConnectivityLevel connectivityLevel = [level intValue];\\n\\n    UIAlertView *alert = [[UIAlertView alloc] initWithTitle: @\\\"Connectivity Alert\\\"\\n                                                    message: level == BPConnectivityNone ? @\\\"No connectivity...\\\" : @\\\"Connected!\\\"\\n                                                   delegate: self\\n                                          cancelButtonTitle: @\\\"OK\\\"\\n                                          otherButtonTitles: nil];\\n    [alert show];\\n}\",\n      \"language\": \"objectivec\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Sample Apps\"\n}\n[/block]\nThe Buddy Platform iOS SDK ships with a number of sample apps to get you started. These can be modified to fit your needs, or just used to guide you through the basics. The sample apps are located in the Samples directory.\n\nThe Buddy SDK is installed into these Apps using Cocoapods. In a Terminal window, cd to the sample project root and type: pod install\n\n## BuddyStarter\n\nDemonstrates simple login and logout. This app implements the authorizationNeedsUserLogin & connectivityChanged selectors on the App Delegate.\n\n## RegisterLogin\n\nDemonstrates another way to implement user registration and login with Buddy. This app implements the authorizationNeedsUserLogin selector on the App Delegate.\n\n## Photo Gallery\n\nThis implements a simple Photo Gallery app where a user can add photos and give them captions and tags. This app is intended to be used in the iOS Simulator.\n\nBefore running the app, verify that you have some photos in your gallery (on the simulator). If not, you can add some using Safari (search for some images, long-click on them and then save them).\n\n## PushChat\n\nThis implements a simple chat app, using Buddy messaging and push notification APIs.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Contributing Back: Pull Requests\"\n}\n[/block]\nWe'd love to have your help making the Buddy SDK as good as it can be!\n\nTo submit a change to the Buddy SDK please do the following:\n\n1. Create your own fork of the Buddy SDK.\n2. Make the change to your fork.\n3. Before creating your pull request, please sync your repository to the current state of the parent repository: git pull origin master.\n4. Commit your changes, then [submit a pull request](https://help.github.com/articles/using-pull-requests) for just that commit.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Questions or need help?\"\n}\n[/block]\nThis should have given you the basics of how to work with the Buddy iOS SDK. If you have further questions or are stuck, send an email to [[email protected]](mailto:[email protected]).","excerpt":"","slug":"ios-sdk","type":"basic","title":"iOS SDK"}
[block:api-header] { "type": "basic", "title": "Overview" } [/block] The Buddy iOS SDK helps you get up and running in seconds. For the most part, the Buddy iOS SDK takes care of all the housekeeping of making requests against the Buddy REST API: * Building and formatting requests * Managing authentication * Parsing responses * Loading and saving credentials With that handled, all you have to do is initialize the SDK and start making some calls! [block:api-header] { "type": "basic", "title": "Getting Started" } [/block] To get started with the Buddy Platform SDK, please reference the Getting Started series of documents at [Intro To Buddy](doc:intro-to-buddy). You will need an App ID and Key before you can use the SDK. The Getting Started documents will walk you through obtaining everything you need and show you where to find the SDK for your platform. Application IDs and Keys are obtained at the Buddy Developer Dashboard at [buddyplatform.com](https://buddyplatform.com). Full documentation for Buddy's services are available at [docs.buddy.com](https://docs.buddy.com). [block:api-header] { "type": "basic", "title": "Installing the SDK" } [/block] ## Prerequisites * iOS 6.0 or greater * Xcode 6.4 or greater The Buddy iOS SDK can be accessed via [Cocoapods](http://cocoapods.org/). Cocoapods version of at least 0.39.0 is required to install the Buddy SDK and sample apps. ## Install with Cocoapods We highly recommend using Cocoapods to install the Buddy SDK. It's fast and makes it much easier to keep up to date with the latest SDK release. If you're new to Cocoapods, see install instructions [here](https://guides.cocoapods.org/using/getting-started.html). Cocoapods depends on Ruby, and depending on your Ruby version the Cocoapods installer may give you trouble; you may need to upgrade Ruby (we recommend using [RVM](https://rvm.io)). (For more Cocoapods troubleshooting steps see [here](https://guides.cocoapods.org/using/troubleshooting#installing-cocoapods)). #### To create a new project using the Buddy SDK: 1\. Create a new Xcode project. 2\. In a Terminal window run: ``` cd <project-dir> ``` 3\. Create a Podfile: ``` touch Podfile ``` 4\. Open the file with your favorite editor and add: ``` platform :ios, '6.0' target '<project name>' do pod 'BuddySDK' end ``` <project name> should be the name of your Xcode project. 5\. If you created a Swift-based project, add: ``` use_frameworks! ``` 6\. Save the Podfile. 7\. In your Terminal window run: ``` pod install ``` 8\. **In Xcode open the just-generated `.xcworkspace` file for your project (not the `.xcodeproj` file).** #### To integrate the Buddy SDK into an existing project: 1\. In a Terminal window run: ``` cd <project-dir> ``` 2\. Create a Podfile: ``` touch Podfile ``` 3\. Open the file with your favorite editor and add: ``` platform :ios, '6.0' target '<project name>' do pod 'BuddySDK' end ``` <project name> should be the name of your Xcode project. 4\. If your project is Swift-based, add: ``` use_frameworks! ``` 5\. Integrating CocoaPods with an existing workspace requires one extra line in your Podfile. Simply specify the relative path and `.xcworkspace` root filename like so: ``` workspace '../MyWorkspace.xcworkspace' ``` 6\. Save the Podfile. 7\. Make sure your workspace is closed in Xcode. Then in your Terminal window run: ``` pod install ``` 8\. **Re-open your `.xcworkspace` file in Xcode.** ## Install from Source Buddy hosts our SDK source on GitHub. To access it, you need to have a GitHub account, and you will also need [Git](http://git-scm.com/download) installed. If you'd like to contribute SDK modifications or additions to Buddy, you'll want to [fork the repository](https://help.github.com/articles/fork-a-repo) so you can issue [pull requests](https://help.github.com/articles/be-social#pull-requests). See the "Contributing Back" section below for details. 1\. In a Terminal window run: ``` git clone https://github.com/BuddyPlatform/Buddy-iOS-SDK.git ``` This will clone the latest version of the SDK into a directory called **Buddy-iOS-SDK.** 2\. Navigate to the **Buddy-iOS-SDK** directory that was created when you cloned the Buddy GitHub repository. The iOS source is in the **Buddy-iOS-SDK\Src** directory. #### Build the GitHub Source To reference the local SDK in your project: 1\. Follow the "Install with Cocoapods" steps above to create a Podfile. 2\. You must add a `:path` parameter to your Podfile to indicate the relative path from your project to the Buddy SDK. It should look something like this: ``` platform :ios, '6.0' target '<project name>' do pod 'BuddySDK', :path => '../../BuddySDK.podspec' end ``` <project name> should be the name of your Xcode project. 3\. Then in your Terminal window run the following. It's ok to do this again if you have already done it: ``` pod install ``` Now any changes you make to the local Buddy SDK source will be picked up by your project when you build it in Xcode. If you add or remove files to the Buddy SDK, you will need to do a `pod update` for your project in a Terminal window. # Using the iOS SDK Visit the [Buddy Dashboard](https://buddyplatform.com/) to obtain an application ID and key, which are needed for your app to communicate with Buddy. Both Objective-C and Swift-based projects are supported. ## Initialize the SDK To reference the Buddy SDK in your source file, you need to put an import keyword at the top of the file that contains your AppDelegate: Objective-C: Open the `AppDelegate.m` file and import the BuddySDK: Swift: Open the `AppDelegate.swift` and import the BuddySDK: [block:code] { "codes": [ { "code": "#import \"BuddySDK/Buddy.h\"", "language": "objectivec" }, { "code": "import BuddySDK", "language": "swift" } ] } [/block] Before you can call any methods in the SDK, it must be initialized. The best place to do this is inside your `AppDelegate.` Initialize your client in the `didFinishLaunchingWithOptions` method: [block:code] { "codes": [ { "code": "[Buddy init:@\"YOUR_APP_ID\" appKey:@\"YOUR_APP_KEY\"];", "language": "objectivec" }, { "code": "Buddy.init(\"YOUR_APP_ID\", appKey: \"YOUR_APP_KEY\");", "language": "swift" } ] } [/block] Replace "YOUR_APP_ID" and "YOUR_APP_KEY" above with your Buddy app's ID and key from the [Buddy Dashboard.](https://buddyplatform.com/) [block:api-header] { "type": "basic", "title": "Example Objective C Calls", "sidebar": true } [/block] The Buddy iOS SDK handles user creation, login, and logout. Here are some example Objective C calls. ## Create A User [block:code] { "codes": [ { "code": "[Buddy createUser:self.signupUsername.text\n password:self.signupPassword.text\n firstName:self.signupFirstName.text\n lastName:self.signupLastName.text\n email:self.signupEmail.text\n dateOfBirth:nil \n gender:nil \n tag:nil \n callback:^(id newBuddyObject, NSError *error)\n{\n if (!error)\n {\n // Greet the user\n }\n}];", "language": "objectivec", "name": "" } ], "sidebar": true } [/block] [block:textarea] { "text": "## User Login", "sidebar": true } [/block] [block:code] { "codes": [ { "code": "[Buddy loginUser:@\"username\" password:@\"password\" callback:^(id newBuddyObject, NSError *error)\n{\n if (!error)\n {\n // Greet the user\n }\n}];", "language": "objectivec" } ], "sidebar": true } [/block] [block:textarea] { "text": "## User Logout", "sidebar": true } [/block] [block:code] { "codes": [ { "code": "[Buddy logoutUser:^(NSError *error) {\n // Perform some action on logout\n}];", "language": "objectivec" } ], "sidebar": true } [/block] ## User Authorization Selector You can implement a selector named `authorizationNeedsUserLogin` on your AppDelegate that gets called whenever a Buddy call is made that requires a logged-in user. That way, you won't have to manage user login state. Here's an example: [block:code] { "codes": [ { "code": "-(void)authorizationNeedsUserLogin\n{ \n // To ensure that login UI is not shown twice if the selector is called multiple times\n if (self.loginPresented == TRUE)\n {\n return;\n }\n self.loginPresented = TRUE;\n\n LoginViewController *loginVC = [[LoginViewController alloc]\n initWithNibName:@\"LoginViewController\" bundle:nil];\n\n [self.navController.topViewController presentViewController:loginVC animated:NO completion:nil];\n}", "language": "objectivec" } ] } [/block] ## REST Interface Each SDK provides wrappers that make REST calls to Buddy. Responses can be handled in two ways: you can create your own wrapper classes, similar to those found in the `Models` folder, or you can use a basic `[NSDictionary class]`. [block:api-header] { "type": "post", "title": "POST" } [/block] In this example we'll create a checkin. Take a look at [Create Checkin](doc:create-checkin) then: [block:code] { "codes": [ { "code": "BPCoordinate *coord = BPCoordinateMake(47.1, -121.292);\n\nNSDictionary *params = @{@\"location\": coord,\n @\"comment\": @\"A comment about this awesome place!\"};\n\n[Buddy POST:@\"/checkins\" parameters:params class:[NSDictionary class] callback:^(id checkin, NSError *error) {\n if (!error) {\n NSLog(@\"Checkin post went as planned\");\n } else {\n NSLog(@\"%@\", error);\n }\n}];", "language": "objectivec" } ] } [/block] [block:api-header] { "type": "get", "title": "GET" } [/block] We now can call GET to search for the checkin we just created! [block:code] { "codes": [ { "code": "BPCoordinateRange *range = BPCoordinateRangeMake(47.1, -121.292, 2500);\n\nNSDictionary *params = @{@\"locationRange\": range};\n\n[Buddy GET:@\"/checkins\" parameters:params class:[BPPageResults class] callback:^(id results, NSError *error) {\n if (!error) {\n NSArray *checkins = [(BPPageResults*)results convertPageResultsToType:[BPCheckin class] ];\n NSLog(@\"%@\", checkins); // Log or do something with the response\n } else {\n NSLog(@\"GET checkins was unsuccessful.\");\n NSLog(@\"%@\", error);\n }\n}];", "language": "objectivec" } ] } [/block] If we wanted to search for the specific checkin, by ID, we can do that too: [block:code] { "codes": [ { "code": "NSString* path = [NSString stringWithFormat:@\"/checkins/%@\", checkinId];\n[Buddy GET:path parameters:nil class:[BPCheckin class] callback:^(id checkin, NSError *error) {\n if (!error) {\n BPCheckin *checkin = (BPCheckin*)checkin;\n // do something with the response\n } else {\n NSLog(@\"GET checkin was unsuccessful.\");\n NSLog(@\"%@\", error);\n }\n}];", "language": "objectivec" } ] } [/block] [block:api-header] { "type": "basic", "title": "PUT/PATCH/DELETE" } [/block] Each remaining REST verb is available through the Buddy SDK using the same pattern as the POST example. [block:api-header] { "type": "basic", "title": "Working With Files" } [/block] Buddy offers support for binary files. The iOS SDK works with files through our REST interface similarly to other API calls. The key class is `BPFile`, which is a wrapper around NSData along with a MIME content type. **Note:** Responses for files deviate from the standard Buddy response templates. See the [Buddy Platform documentation](https://docs.buddy.com) for more information. [block:api-header] { "type": "basic", "title": "Upload A File" } [/block] Here we demonstrate uploading a picture. All binary files use the same pattern with a different path and different parameters. To upload a picture POST to `"/pictures"`: [block:code] { "codes": [ { "code": "BPFile *file = [[BPFile alloc] init];\nfile.contentType = @\"image/jpg\";\nfile.fileData = UIImageJPEGRepresentation(koi, .75);\n\nNSDictionary *parameters = @{@\"data\": file,\n @\"caption\": @\"Koi are awesome fish.\"};\n\n[Buddy POST:@\"/pictures\" parameters:parameters class:[NSDictionary class] callback:^(id picture, NSError *error) {\n if (!error) {\n NSLog(@\"Image uploaded successfully\");\n } else {\n NSLog(@\"Image upload went wrong\");\n NSLog(@\"%@\", error);\n }\n}];", "language": "objectivec" } ] } [/block] [block:api-header] { "type": "basic", "title": "Download A File" } [/block] To download a file send a GET request with BPFile as the operation type. This sample downloads the picture we uploaded in the "Upload File" example: [block:code] { "codes": [ { "code": "// Don't forget to store the picture ID in pictureId!\n\n[Buddy GET:[NSString stringWithFormat:@\"/pictures/%@/file\", pictureId] parameters:nil class:[BPFile class] callback:^(id obj, NSError *error) { \n if (!error)\n {\n BPFile *file = (BPFile*)obj;\n\n UIImage* image = [UIImage imageWithData:file.fileData];\n // Do something with the image!\n\n NSLog(@\"Image download successful\");\n } else {\n NSLog(@\"Something went wrong\");\n }\n\n}];", "language": "objectivec" } ] } [/block] [block:api-header] { "type": "basic", "title": "Advanced Usage" } [/block] ## Automatically report location for each Buddy call If you set the current location in the Buddy client, each time a Buddy call is made that location will be passed in the call. Most calls that send data to Buddy have a location parameter; if a call is made that doesn't take location, the parameter will be ignored. [block:code] { "codes": [ { "code": "BPCoordinate *location = BPCoordinateMake(47.1, -121.292);\n\n[Buddy setLastLocation: location];", "language": "objectivec" } ] } [/block] ## Multiple concurrent users If you need to have multiple clients (for example if you need to interact with multiple users concurrently from your app), you can capture clients created from `Buddy.init` and use those clients individually: [block:code] { "codes": [ { "code": "id<BuddyClientProtocol> client1 = [Buddy init:@\"Your App ID 1\" appKey:@\"Your App Key1\"];\n\nid<BuddyClientProtocol> client2 = [Buddy init:@\"Your App ID 2\" appKey:@\"Your App Key2\"];\n\n[client1 loginUser:@\"user1\" password:@\"password1\" callback:<#^(id newBuddyObject, NSError *error)callback#>\n{\n if (!error)\n {\n // Greet user1\n }\n}];\n\n[client2 loginUser:@\"user2\" password:@\"password2\" callback:<#^(id newBuddyObject, NSError *error)callback#>\n {\n if (!error)\n {\n // Greet user2\n }\n }];", "language": "objectivec" } ] } [/block] ## Handling connectivity You can implement a selector named `connectivityChanged` on your AppDelegate if you would like to be notified if your device loses and regains ability to communicate to the Buddy servers for whatever reason. Here's an example that notifies the user: [block:code] { "codes": [ { "code": "- (void)connectivityChanged:(NSNumber *)level\n{\n BPConnectivityLevel connectivityLevel = [level intValue];\n\n UIAlertView *alert = [[UIAlertView alloc] initWithTitle: @\"Connectivity Alert\"\n message: level == BPConnectivityNone ? @\"No connectivity...\" : @\"Connected!\"\n delegate: self\n cancelButtonTitle: @\"OK\"\n otherButtonTitles: nil];\n [alert show];\n}", "language": "objectivec" } ] } [/block] [block:api-header] { "type": "basic", "title": "Sample Apps" } [/block] The Buddy Platform iOS SDK ships with a number of sample apps to get you started. These can be modified to fit your needs, or just used to guide you through the basics. The sample apps are located in the Samples directory. The Buddy SDK is installed into these Apps using Cocoapods. In a Terminal window, cd to the sample project root and type: pod install ## BuddyStarter Demonstrates simple login and logout. This app implements the authorizationNeedsUserLogin & connectivityChanged selectors on the App Delegate. ## RegisterLogin Demonstrates another way to implement user registration and login with Buddy. This app implements the authorizationNeedsUserLogin selector on the App Delegate. ## Photo Gallery This implements a simple Photo Gallery app where a user can add photos and give them captions and tags. This app is intended to be used in the iOS Simulator. Before running the app, verify that you have some photos in your gallery (on the simulator). If not, you can add some using Safari (search for some images, long-click on them and then save them). ## PushChat This implements a simple chat app, using Buddy messaging and push notification APIs. [block:api-header] { "type": "basic", "title": "Contributing Back: Pull Requests" } [/block] We'd love to have your help making the Buddy SDK as good as it can be! To submit a change to the Buddy SDK please do the following: 1. Create your own fork of the Buddy SDK. 2. Make the change to your fork. 3. Before creating your pull request, please sync your repository to the current state of the parent repository: git pull origin master. 4. Commit your changes, then [submit a pull request](https://help.github.com/articles/using-pull-requests) for just that commit. [block:api-header] { "type": "basic", "title": "Questions or need help?" } [/block] This should have given you the basics of how to work with the Buddy iOS SDK. If you have further questions or are stuck, send an email to [[email protected]](mailto:[email protected]).