{"_id":"56c2bc123e1b8d2300fe4ca0","project":"56bc8e679afb8b0d00d62dcf","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"},"__v":28,"parentDoc":null,"user":"56b98db7bb36440d0001f492","updates":[],"next":{"pages":[],"description":""},"createdAt":"2016-02-16T06:05:06.580Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"results":{"codes":[]},"settings":"","auth":"required","params":[],"url":""},"isReference":false,"order":6,"body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Overview\"\n}\n[/block]\nThe Buddy Android SDK helps you get up and running in seconds.\n\nFor the most part, the Buddy Android 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 [docs.buddy.com](https://docs.buddy.com). You will need an Application 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/login).\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## Install from Maven/Gradle\n\n1\\. Ensure that you have Android Studio installed.\n2\\. Open your project in Android Studio. In your application's module build.gradle file, under 'dependencies', add a line for the Buddy Android SDK dependency:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"dependencies {\\n    compile fileTree(dir: 'libs', include: ['*.jar'])\\n    compile 'com.buddy:androidsdk:+'\\n}\",\n      \"language\": \"java\",\n      \"name\": \"build.gradle\"\n    }\n  ]\n}\n[/block]\n3\\. Go to File > Project Structure and select the Project tab. Change the `Default Library Repository` from `jcenter` to `mavenCentral`.\n\nThis will install the latest release of the Buddy Android SDK. **Note:** If you wish to limit yourself to a narrower set of releases, you can do so like this (e.g. the latest release in the 3.0.0 series):\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"compile 'com.buddy:androidsdk:3.0.0+'\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\n## Install from Source\n\n## Getting the Source\n\nBuddy hosts our SDK source on GitHub. To access it you need to have [Git](https://git-scm.com/ 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\nFrom a cmd window or terminal, type:\n\n```\ngit clone https://github.com/BuddyPlatform/Buddy-Android-SDK.git\n```\nThis will copy the latest source of the SDK into a directory called *Buddy-Android-SDK*.\n\n## Build Prerequisites\n\nTo build the SDK you need to:\n\n1. Install Android Studio. You may be asked to install a compatible version of the Java SE Development Kit, if you don't already have it installed.\n2. Open the Android SDK Manager and make sure you have installed Android SDK Build-tools 23.0.3 and Android 4.4.2 (API 19).\n\n## Build and Install\n\n  1. Open a terminal window (Mac) or a cmd window (Windows).\n  2. From the root of the Buddy-Android-SDK repository, run ./gradlew build (Mac/Linux) or gradlew.bat build (Windows) to build the SDK\n  3. Look in the library/build/libs directory to find built JARs, and the library/build/outputs/aar/ directory to find built AARs.\n  4. Add the buddy-sdk-release.aar file as a dependency for your Android application by doing the following:\n      a. Add the ':buddy-sdk-release' module reference to your application's settings.gradle file:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"include ':app', ':buddy-sdk-release'\",\n      \"language\": \"java\",\n      \"name\": \"settings.gradle\"\n    }\n  ]\n}\n[/block]\n  b. Add a buddy-sdk-release/build.gradle module file, with a relative path between your project and the SDK's .aar location in your file system:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"configurations.maybeCreate(\\\"default\\\")\\nartifacts.add(\\\"default\\\", file('../../../library/build/outputs/aar/buddy-sdk-release.aar'))\",\n      \"language\": \"java\",\n      \"name\": \"buddy-sdk-release/build.gradle\"\n    }\n  ]\n}\n[/block]\n  c. Modify the dependencies { ... } block of your application's module build.gradle file. Be sure to add the android-async-http and gson dependencies:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"dependencies {\\n    // Add the following dependencies:\\n    compile 'com.loopj.android:android-async-http:1.4.8'\\n    compile 'com.google.code.gson:gson:2.4'\\n    compile project(':buddy-sdk-release')\\n}\",\n      \"language\": \"java\",\n      \"name\": \"app/build.gradle\"\n    }\n  ]\n}\n[/block]\nTo see an example of the above, check out the BuddyChat sample app's project configuration.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Using the Android SDK\",\n  \"sidebar\": true\n}\n[/block]\nVisit the [Buddy Dashboard](https://buddyplatform.com/) to obtain your application ID and key.\n\n## Referencing the SDK\n\nTo use the SDK from your Java code, you need to import the SDK. You can do so as follows:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import com.buddy.sdk.*;\\nimport com.buddy.sdk.models.*;\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\n## Initialize the SDK\n\nThis should either be done in the `onCreate` method of your Application class (if you have one), or in the `onCreate` method of your launch Activity. You should pass in an Application or Activity Context if it's available:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"import com.buddy.sdk.*;\\nimport com.buddy.sdk.models.*;\\n...\\nContext myContext = getApplicationContext(); // If there is no context, set myContext to null\\nBuddy.init(myContext, \\\"appId\\\", \\\"appKey\\\")\",\n      \"language\": \"java\",\n      \"name\": \"\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n## User Flow\n\nThere are helper functions for creating, logging in, and logging out users, and a callback to manage login state:\n\n## Create User\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Buddy.createUser(\\\"someUser\\\", \\\"somePassword\\\", null, null, null, null, null, null, new BuddyCallback<User>(User.class) {\\n  :::at:::Override\\n  public void completed(BuddyResult<User> result) {\\n    if (result.getIsSuccess()) {\\n      Log.w(APP_LOG, \\\"User created: \\\" + result.getResult().userName);\\n    }\\n  }\\n});\",\n      \"language\": \"java\",\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(\\\"someUser\\\", \\\"somePassword\\\", new BuddyCallback<User>(User.class) {...});\",\n      \"language\": \"java\",\n      \"name\": \"\"\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();\",\n      \"language\": \"java\",\n      \"name\": \"\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n## User Login/Logout Callback\n\nWe recommend implementing a `UserAuthenticationRequiredCallback` callback. It will get called whenever you make a Buddy call that needs an authorized user, and a user isn't logged in. That way, you won't have to manage user login state. Here's an example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Buddy.setUserAuthenticationRequiredCallback(new UserAuthenticationRequiredCallback() {\\n    @Override\\n    public void authenticate() {\\n        // The below is an example of how to call a 'login' Activity\\n        Intent loginIntent = new Intent(MyBuddyApplication.this, Login.class);\\n        loginIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);\\n        startActivity(loginIntent);\\n    }\\n});\",\n      \"language\": \"java\",\n      \"name\": \"\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n## Rest Interface\n\nEach SDK provides general wrappers that make REST calls to Buddy. For call responses, you can either create a wrapper Java class such as those found in com.buddy.sdk.models, or you can simply pass a type of JsonObject to return a standard Gson JsonObject.\n[block:api-header]\n{\n  \"type\": \"post\",\n  \"title\": \"POST\"\n}\n[/block]\nIn this example we will create a checkin. Take a look at [Create Checkin](doc:create-checkin), then:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Location location = new Location(\\\"\\\");\\nlocation.setLatitude(47.61d);\\nlocation.setLongitude(-122.33d);\\n\\nMap<String,Object> parameters = new HashMap<String,Object>();\\nparameters.put(\\\"comment\\\", \\\"My first checkin\\\");\\nparameters.put(\\\"description\\\", \\\"This is where I was doing that thing.\\\");\\nparameters.put(\\\"location\\\", location);\\n\\nBuddy.<Checkin>post(\\\"/checkins\\\", parameters, new BuddyCallback<Checkin>(Checkin.class) {\\n    @Override\\n    public void completed(BuddyResult<Checkin> result) {\\n        if (result.getIsSuccess()) {\\n            Checkin checkin = result.getResult();\\n            // get the ID of the created checkin.\\n            String id = checkin.id;\\n        }\\n    }\\n});\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"get\",\n  \"title\": \"GET\"\n}\n[/block]\nThis example searches for the checkin we created in the POST example. See [Search Checkins](doc:search-checkins) for a full list of parameters.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Map<String, Object> parameters = new HashMap<String, Object>();\\nparameters.put(\\\"locationRange\\\", \\\"47.61, -122.33, 1500\\\");\\n\\nBuddy.<JsonObject>get(\\\"/checkins\\\", parameters, new BuddyCallback<JsonObject>(JsonObject.class) {\\n    @Override\\n    public void completed(BuddyResult<JsonObject> result) {\\n        if (result.getIsSuccess()) {\\n            JsonObject obj = result.getResult();\\n            // Get the pageResults response as a JsonArray\\n            JsonArray _res = obj.get(\\\"pageResults\\\").getAsJsonArray();\\n            Log.w(APP_LOG, _res.toString());\\n        }\\n    }\\n});\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"put\",\n  \"title\": \"PUT/PATCH/DELETE\"\n}\n[/block]\nEach remaining supported REST verb is available through the Buddy SDK using the same pattern as the POST and GET examples.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"File Management\"\n}\n[/block]\nBuddy offers support for binary files. The Android SDK works with files through our REST interface similarly to other API calls.\n\n## Upload a file\n\nThe Buddy Android SDK handles all necessary file management for you. The key class is `com.buddy.sdk.BuddyFile`, which is a wrapper around an Android `File` or `InputStream`, along with a MIME content type. Here we demonstrate uploading a picture. All binary files use the same pattern, with a different API path and different parameters. Here's an example of uploading a picture:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"BuddyFile buddyFile = new BuddyFile(new File(...), \\\"image/jpg\\\");\\nMap<String,Object> parameters = new HashMap<String,Object>();\\nparameters.put(\\\"caption\\\", \\\"From Android\\\");\\nparameters.put(\\\"data\\\", buddyFile);\\n\\nString pictureId;\\nBuddy.<Picture>post(\\\"/pictures\\\", parameters, new BuddyCallback<Picture>(Picture.class){\\n    @Override\\n    public void completed(BuddyResult<Picture> result) {\\n        if (result.getIsSuccess()) {\\n            pictureId = result.getResult().id;\\n            Log.w(APP_LOG, \\\"It worked!\\\");\\n        }\\n    }\\n});\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\n## Download a file\n\nTo download a file send a GET request with BuddyFile as the operation type. This sample downloads the picture we uploaded in the \"Upload a File\" example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"Buddy.get(String.format(\\\"/pictures/%s/file\\\", pictureId), null, new BuddyCallback<BuddyFile>(BuddyFile.class) {\\n    @Override\\n    public void completed(BuddyResult<BuddyFile> file) {\\n        // Do something with your picture!\\n        Log.w(APP_LOG, file.getResult().getContentType());\\n        // The picture's binary data is in the stream property\\n        InputStream stream = file.getResult().getStream();\\n    }\\n});\",\n      \"language\": \"java\"\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, 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\": \"Location loc = new Location(\\\"My Location\\\");\\nloc.setLatitude(47);\\nloc.setLongitude(-122);\\nBuddy.setLastLocation(loc);\",\n      \"language\": \"java\"\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\": \"BuddyClientOptions opt1 = new BuddyClientOptions();\\nopt1.instanceName = \\\"client1\\\";\\n\\nBuddyClient client1 = Buddy.init(app1, key1, opt1);\\n\\nBuddyClientOptions opt2 = new BuddyClientOptions();\\nopt1.instanceName = \\\"client2\\\";\\n\\nBuddyClient client2 = Buddy.init(app1, key1, opt2);\\n\\nclient1.loginUser(\\\"user1\\\", \\\"pw1\\\", null);\\nclient2.loginUser(\\\"user2\\\", \\\"pw2\\\", null);\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\nThe `Buddy` static class has the same signature as the `BuddyClient` class, and is shorthand for calling the most recently created client via a `Buddy.init()` call.\n\n## Handling connectivity\n\nYou can set the `ConnectivityLevelChangedCallback` callback 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\": \"Buddy.setConnectivityLevelChangedCallback(new ConnectivityLevelChangedCallback() {\\n    @Override\\n    public void connectivityLevelChanged(ConnectivityLevel level) {\\n        String message = (level == ConnectivityLevel.None) ? \\\"Connectivity lost...\\\" : \\\"Reconnected!\\\";\\n        Toast toast = Toast.makeText(getApplicationContext(), message, Toast.LENGTH_LONG);\\n        toast.setGravity(Gravity.TOP, 0, 0);\\n        toast.show();\\n    }\\n});\",\n      \"language\": \"java\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Sample Apps\"\n}\n[/block]\n## BuddyChat\n\nBuddyChat is an example of how to use Buddy's push notification and messaging support to create a simple chat application.\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 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 Android SDK. If you have further questions or are stuck, send an email to [[email protected]](mailto:[email protected]).","excerpt":"","slug":"android-sdk","type":"basic","title":"Android SDK"}
[block:api-header] { "type": "basic", "title": "Overview" } [/block] The Buddy Android SDK helps you get up and running in seconds. For the most part, the Buddy Android 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 [docs.buddy.com](https://docs.buddy.com). You will need an Application 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/login). 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] ## Install from Maven/Gradle 1\. Ensure that you have Android Studio installed. 2\. Open your project in Android Studio. In your application's module build.gradle file, under 'dependencies', add a line for the Buddy Android SDK dependency: [block:code] { "codes": [ { "code": "dependencies {\n compile fileTree(dir: 'libs', include: ['*.jar'])\n compile 'com.buddy:androidsdk:+'\n}", "language": "java", "name": "build.gradle" } ] } [/block] 3\. Go to File > Project Structure and select the Project tab. Change the `Default Library Repository` from `jcenter` to `mavenCentral`. This will install the latest release of the Buddy Android SDK. **Note:** If you wish to limit yourself to a narrower set of releases, you can do so like this (e.g. the latest release in the 3.0.0 series): [block:code] { "codes": [ { "code": "compile 'com.buddy:androidsdk:3.0.0+'", "language": "java" } ] } [/block] ## Install from Source ## Getting the Source Buddy hosts our SDK source on GitHub. To access it you need to have [Git](https://git-scm.com/ 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. From a cmd window or terminal, type: ``` git clone https://github.com/BuddyPlatform/Buddy-Android-SDK.git ``` This will copy the latest source of the SDK into a directory called *Buddy-Android-SDK*. ## Build Prerequisites To build the SDK you need to: 1. Install Android Studio. You may be asked to install a compatible version of the Java SE Development Kit, if you don't already have it installed. 2. Open the Android SDK Manager and make sure you have installed Android SDK Build-tools 23.0.3 and Android 4.4.2 (API 19). ## Build and Install 1. Open a terminal window (Mac) or a cmd window (Windows). 2. From the root of the Buddy-Android-SDK repository, run ./gradlew build (Mac/Linux) or gradlew.bat build (Windows) to build the SDK 3. Look in the library/build/libs directory to find built JARs, and the library/build/outputs/aar/ directory to find built AARs. 4. Add the buddy-sdk-release.aar file as a dependency for your Android application by doing the following: a. Add the ':buddy-sdk-release' module reference to your application's settings.gradle file: [block:code] { "codes": [ { "code": "include ':app', ':buddy-sdk-release'", "language": "java", "name": "settings.gradle" } ] } [/block] b. Add a buddy-sdk-release/build.gradle module file, with a relative path between your project and the SDK's .aar location in your file system: [block:code] { "codes": [ { "code": "configurations.maybeCreate(\"default\")\nartifacts.add(\"default\", file('../../../library/build/outputs/aar/buddy-sdk-release.aar'))", "language": "java", "name": "buddy-sdk-release/build.gradle" } ] } [/block] c. Modify the dependencies { ... } block of your application's module build.gradle file. Be sure to add the android-async-http and gson dependencies: [block:code] { "codes": [ { "code": "dependencies {\n // Add the following dependencies:\n compile 'com.loopj.android:android-async-http:1.4.8'\n compile 'com.google.code.gson:gson:2.4'\n compile project(':buddy-sdk-release')\n}", "language": "java", "name": "app/build.gradle" } ] } [/block] To see an example of the above, check out the BuddyChat sample app's project configuration. [block:api-header] { "type": "basic", "title": "Using the Android SDK", "sidebar": true } [/block] Visit the [Buddy Dashboard](https://buddyplatform.com/) to obtain your application ID and key. ## Referencing the SDK To use the SDK from your Java code, you need to import the SDK. You can do so as follows: [block:code] { "codes": [ { "code": "import com.buddy.sdk.*;\nimport com.buddy.sdk.models.*;", "language": "java" } ] } [/block] ## Initialize the SDK This should either be done in the `onCreate` method of your Application class (if you have one), or in the `onCreate` method of your launch Activity. You should pass in an Application or Activity Context if it's available: [block:code] { "codes": [ { "code": "import com.buddy.sdk.*;\nimport com.buddy.sdk.models.*;\n...\nContext myContext = getApplicationContext(); // If there is no context, set myContext to null\nBuddy.init(myContext, \"appId\", \"appKey\")", "language": "java", "name": "" } ], "sidebar": true } [/block] ## User Flow There are helper functions for creating, logging in, and logging out users, and a callback to manage login state: ## Create User [block:code] { "codes": [ { "code": "Buddy.createUser(\"someUser\", \"somePassword\", null, null, null, null, null, null, new BuddyCallback<User>(User.class) {\n @Override\n public void completed(BuddyResult<User> result) {\n if (result.getIsSuccess()) {\n Log.w(APP_LOG, \"User created: \" + result.getResult().userName);\n }\n }\n});", "language": "java", "name": "" } ], "sidebar": true } [/block] [block:textarea] { "text": "## User Login", "sidebar": true } [/block] [block:code] { "codes": [ { "code": "Buddy.loginUser(\"someUser\", \"somePassword\", new BuddyCallback<User>(User.class) {...});", "language": "java", "name": "" } ], "sidebar": true } [/block] [block:textarea] { "text": "## User Logout", "sidebar": true } [/block] [block:code] { "codes": [ { "code": "Buddy.logoutUser();", "language": "java", "name": "" } ], "sidebar": true } [/block] ## User Login/Logout Callback We recommend implementing a `UserAuthenticationRequiredCallback` callback. It will get called whenever you make a Buddy call that needs an authorized user, and a user isn't logged in. That way, you won't have to manage user login state. Here's an example: [block:code] { "codes": [ { "code": "Buddy.setUserAuthenticationRequiredCallback(new UserAuthenticationRequiredCallback() {\n @Override\n public void authenticate() {\n // The below is an example of how to call a 'login' Activity\n Intent loginIntent = new Intent(MyBuddyApplication.this, Login.class);\n loginIntent.setFlags(Intent.FLAG_ACTIVITY_NEW_TASK);\n startActivity(loginIntent);\n }\n});", "language": "java", "name": "" } ], "sidebar": true } [/block] ## Rest Interface Each SDK provides general wrappers that make REST calls to Buddy. For call responses, you can either create a wrapper Java class such as those found in com.buddy.sdk.models, or you can simply pass a type of JsonObject to return a standard Gson JsonObject. [block:api-header] { "type": "post", "title": "POST" } [/block] In this example we will create a checkin. Take a look at [Create Checkin](doc:create-checkin), then: [block:code] { "codes": [ { "code": "Location location = new Location(\"\");\nlocation.setLatitude(47.61d);\nlocation.setLongitude(-122.33d);\n\nMap<String,Object> parameters = new HashMap<String,Object>();\nparameters.put(\"comment\", \"My first checkin\");\nparameters.put(\"description\", \"This is where I was doing that thing.\");\nparameters.put(\"location\", location);\n\nBuddy.<Checkin>post(\"/checkins\", parameters, new BuddyCallback<Checkin>(Checkin.class) {\n @Override\n public void completed(BuddyResult<Checkin> result) {\n if (result.getIsSuccess()) {\n Checkin checkin = result.getResult();\n // get the ID of the created checkin.\n String id = checkin.id;\n }\n }\n});", "language": "java" } ] } [/block] [block:api-header] { "type": "get", "title": "GET" } [/block] This example searches for the checkin we created in the POST example. See [Search Checkins](doc:search-checkins) for a full list of parameters. [block:code] { "codes": [ { "code": "Map<String, Object> parameters = new HashMap<String, Object>();\nparameters.put(\"locationRange\", \"47.61, -122.33, 1500\");\n\nBuddy.<JsonObject>get(\"/checkins\", parameters, new BuddyCallback<JsonObject>(JsonObject.class) {\n @Override\n public void completed(BuddyResult<JsonObject> result) {\n if (result.getIsSuccess()) {\n JsonObject obj = result.getResult();\n // Get the pageResults response as a JsonArray\n JsonArray _res = obj.get(\"pageResults\").getAsJsonArray();\n Log.w(APP_LOG, _res.toString());\n }\n }\n});", "language": "java" } ] } [/block] [block:api-header] { "type": "put", "title": "PUT/PATCH/DELETE" } [/block] Each remaining supported REST verb is available through the Buddy SDK using the same pattern as the POST and GET examples. [block:api-header] { "type": "basic", "title": "File Management" } [/block] Buddy offers support for binary files. The Android SDK works with files through our REST interface similarly to other API calls. ## Upload a file The Buddy Android SDK handles all necessary file management for you. The key class is `com.buddy.sdk.BuddyFile`, which is a wrapper around an Android `File` or `InputStream`, along with a MIME content type. Here we demonstrate uploading a picture. All binary files use the same pattern, with a different API path and different parameters. Here's an example of uploading a picture: [block:code] { "codes": [ { "code": "BuddyFile buddyFile = new BuddyFile(new File(...), \"image/jpg\");\nMap<String,Object> parameters = new HashMap<String,Object>();\nparameters.put(\"caption\", \"From Android\");\nparameters.put(\"data\", buddyFile);\n\nString pictureId;\nBuddy.<Picture>post(\"/pictures\", parameters, new BuddyCallback<Picture>(Picture.class){\n @Override\n public void completed(BuddyResult<Picture> result) {\n if (result.getIsSuccess()) {\n pictureId = result.getResult().id;\n Log.w(APP_LOG, \"It worked!\");\n }\n }\n});", "language": "java" } ] } [/block] ## Download a file To download a file send a GET request with BuddyFile as the operation type. This sample downloads the picture we uploaded in the "Upload a File" example: [block:code] { "codes": [ { "code": "Buddy.get(String.format(\"/pictures/%s/file\", pictureId), null, new BuddyCallback<BuddyFile>(BuddyFile.class) {\n @Override\n public void completed(BuddyResult<BuddyFile> file) {\n // Do something with your picture!\n Log.w(APP_LOG, file.getResult().getContentType());\n // The picture's binary data is in the stream property\n InputStream stream = file.getResult().getStream();\n }\n});", "language": "java" } ] } [/block] [block:api-header] { "type": "basic", "title": "Advanced Usage" } [/block] ## Automatically report location for each Buddy call If you set the current location, 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": "Location loc = new Location(\"My Location\");\nloc.setLatitude(47);\nloc.setLongitude(-122);\nBuddy.setLastLocation(loc);", "language": "java" } ] } [/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": "BuddyClientOptions opt1 = new BuddyClientOptions();\nopt1.instanceName = \"client1\";\n\nBuddyClient client1 = Buddy.init(app1, key1, opt1);\n\nBuddyClientOptions opt2 = new BuddyClientOptions();\nopt1.instanceName = \"client2\";\n\nBuddyClient client2 = Buddy.init(app1, key1, opt2);\n\nclient1.loginUser(\"user1\", \"pw1\", null);\nclient2.loginUser(\"user2\", \"pw2\", null);", "language": "java" } ] } [/block] The `Buddy` static class has the same signature as the `BuddyClient` class, and is shorthand for calling the most recently created client via a `Buddy.init()` call. ## Handling connectivity You can set the `ConnectivityLevelChangedCallback` callback 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": "Buddy.setConnectivityLevelChangedCallback(new ConnectivityLevelChangedCallback() {\n @Override\n public void connectivityLevelChanged(ConnectivityLevel level) {\n String message = (level == ConnectivityLevel.None) ? \"Connectivity lost...\" : \"Reconnected!\";\n Toast toast = Toast.makeText(getApplicationContext(), message, Toast.LENGTH_LONG);\n toast.setGravity(Gravity.TOP, 0, 0);\n toast.show();\n }\n});", "language": "java" } ] } [/block] [block:api-header] { "type": "basic", "title": "Sample Apps" } [/block] ## BuddyChat BuddyChat is an example of how to use Buddy's push notification and messaging support to create a simple chat application. [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 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 Android SDK. If you have further questions or are stuck, send an email to [[email protected]](mailto:[email protected]).