Skip to content

Embedding our SDK

Jump to bottom
Andrew Tremblay edited this page May 26, 2014 · 48 revisions

There are two ways to include AppBlade in your project, directly using the source code or including an AppBlade binary. We officially suggest that you compile from source, preferably as a git submodule, but for programmers less familiar with using external sources we have also provided our own builds of the AppBlade SDK.

##Add AppBlade to your project# This guide is for our Android and iOS native code. If you're looking for our Plugins, they can be found in their own repositories.


- [Android](https://github.com/AppBlade/AppBladeSDK/wiki/Embedding-our-SDK#wiki-android-sdk) - [Embedding the Source](https://github.com/AppBlade/AppBladeSDK/wiki/Embedding-our-SDK#wiki-adding-android-source) - [Embedding the Binary](https://github.com/AppBlade/AppBladeSDK/wiki/Embedding-our-SDK#wiki-adding-android-binary) - [Using ProGuard](https://github.com/AppBlade/AppBladeSDK/wiki/Embedding-our-SDK#using-proguard)

#iOS SDK# ###Common Gotchas###

  • Before starting, make sure you have created a project on AppBlade for the SDK to communicate to.
  • Confirm that you have the latest version of Xcode installed. The most up-to-date version of Xcode isn't required to use AppBlade, but it's what we would use. Plus it's just good practice.
  • Due to Apple's new device identification policy starting May 1st 2013, all apps submitted to the App Store with the AppBlade SDK embedded should be using our latest SDK which implements AppBlade API version 3. If you would like to still use our previous SDK, directions for embedding that can be found here.
  • The AppBlade framework is ARC-agnostic; It uses ARC, but is compatible with ARC-disabled projects.

##Walkthrough## Embedding the AppBlade SDK and getting it up and running is fairly simple to do:

  1. Add your AppBlade SDK library files.
  2. Add your property lists.
  3. Build and Run!

There are a few optional steps that can help you do special things

###1. Add your AppBlade SDK Library Files### Adding the AppBlade SDK library files can be done in one of two following ways:

  1. Adding a binary
  2. Adding the source

If you'd like to compile your own binaries from source, we've got a guide for that.

###Including AppBlade Source### Some prefer to include the AppBlade source code directly to their project, either as a submodule for easier code updates or for development on new AppBlade features. AppBlade binaries should not be included if the source code is being used directly instead. Integrating source is a slightly more advanced process and not recommended for beginners.

  1. Clone the AppBlade master branch off of github, then drag the AppBlade project file into the left-hand File Navigator of your application's Xcode project.
    • NOTE: If you are also sharing this project with others (through github, for example) it is highly suggested that you use a copy of the AppBlade Framework in a subdirectory into your project instead of an external one. You may either simply copy iOS/Framework into your project folder or add AppBlade as a Submodule.
  2. Select the following options in the add file options panel and before clicking "Finish":
    • Make sure that "Copy items" is checked for "Destination".
    • Check each of your app targets in "Add to targets".
  3. Add the Apple Security.framework and the libsqlite3.dlyb to your project.
    • Click your project file from the File Navigator and then select your app target from the list on the right.
    • Select the "Build Phases" tab and expand "Link Binary With Libraries" and click the "+" button to add a library.
    • Select Security.framework and libsqlite3.dlyb from the list and click "Add".
  4. Add the Appblade library to your Target Dependencies
    • From the "Build Phases" tab, expand "Target Dependencies" and click the "+" button to add a library.
    • Select the AppBlade target under your AppBlade subproject in the dropdown.
  5. Link the Appblade binary to your Link Binary With Libraries
    • From the "Build Phases" tab, expand "Link Binary With Libraries" and click the "+" button to add a binary.
    • Select the AppBlade.a binary under your Workspace folder in the appearing dropdown.
  6. Link the Appblade header files to your Project
    • In your Project Build Settings (Not your Target Build Settings), scroll down to Header Search Paths.
    • Add the path of your AppBlade iOS/Framework folder to your Header Search Paths. Make sure it is marked recursive.
  7. Progress! Next we add your property lists.

###Including AppBlade Binary## You can either download the compiled version from our website, or build the AppBlade library from downloaded source (directions for which can be found in the Building AppBlade Binary From Source section).

1. After downloading AppBlade or building it locally, navigate to the folder containing the libAppBladeUniversal.a binary and header file. In this case we're using the files from our website.

!

2. Open your Xcode project.

3. For a universal build, simply drag the libAppBladeUniversal.a and AppBlade.h files from the folder into your project, ensure that "Copy items" is checked and that it is linked to your build target.

!

4. Click your project file from the File Navigator and then select your app target from the list on the right.

5. Select the "Build Phases" tab and expand "Link Binary With Libraries", your libAppBladeUniversal.a lib should already be in there if you linked your target.

!

6. The AppBlade SDK has only two external dependencies:

  • Security.framework

  • and libsqlite3.dlyb

Click the "+" button under "Link Binary With Libraries" to add them. Select or search for the dependencies from the list and click "Add" to confirm.

!

7. Again, make sure libAppBladeUniversal.a is also added to the list if it hasn't been added by Xcode.

8. Progress! Next we add your property lists.

###2. Add Your Property Lists.### Okay, so you added our library, either by binary or source. The AppBlade library will now build and link to your project on each build of this target, but you'll need to add property lists (.plists) in order for AppBlade.com to use your builds.

1. First, grab your property lists. Again, these are from the folder on AppBlade.com

!

2. Open your Xcode project in Finder and drag or copy both plist files into the base folder of your project. The plists must be in this base folder and nowhere else.

!

3. Navigate to your Copy Bundle Resources section in your project settings.

!

4. Add your resources by selecting the + at the bottom of the Add Resources section and selecting "Add Other..."

!

5. Navigate out of the project file (which is where the file browser drops you for some reason) and into the base project folder.

!

6. Select the files you added earlier to the base project folder and click Open.

!

7. In the confirm panel, make sure the "Copy items" option is NOT checked and, if you have any build targets visible, that they are selected.

!

8. Looking back at the build settings, things should look something like this:

!

9. In your AppBlade project, click your API Keys.

In the modal that appears, copy your Development Secret (If you are updating your SDK, this is the value that was once your project secret). Back in your SDK embedded Application, open your AppBladeKeys.plist and copy the key from your project into the project_secret key/value (replacing the value that says "your_project_secret_here").

10. Your property lists are now added. Your key is embedded. Everything should work, time to build and run!

###3. Build and Run!### Home stretch! You've embedded the SDK and your property lists, now all you need to do is prove it's building properly.

  1. In your App Delegate file, import AppBlade.h, The Xcode auto-complete should be able to find it.

  2. Add the following lines to your - (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions method:

    AppBlade *blade = [AppBlade sharedManager];
[blade registerWithAppBladePlist];

In the end everything should look something like this:

! (Notice that we moved our AppBlade files in our project for better organization, you can too.)

Now hit run. Congratulations!

!

##What Next?## Check out our Feature Implementation Guide to see what our SDK can do.

##Still having problems?## Check out our FAQ (Frequent AppBlade Questions).

#Android SDK# Before starting, know that our minimum supported Android API is 9 and our target API is 17.

The Android AppBlade SDK has only one dependency; httpmime-4.1.2.jar, (org.apache.http.entity.mime) which is used for network calls. This may conflict with certain projects. Compiling from source and controlling the dependencies manually will resolve most issues.
Currently we only provide directions for the Eclipse environment because that is what we use everyday. Ensure you have Google's ADT plugin for Eclipse (Google provides documentation on how to add their Eclipse plugin).

###Adding Android Source###

  1. First have our source copied locally, either with a git clone call or a tag download from github.
    Make sure you also start with an existing android project in your workspace.
  2. Import the android source code into your project workspace.
  • In your Eclipse Package Explorer, Right click and select Import...
  • In the import selection window Select Android -> Existing Android Code Into Workspace
  • On the next screen, navigate your browser to the local AppBlade Framework location. (In our source this is located under /Android/AppBlade Framework).
  • Select the project named "AppBlade Framework" in the list and click Finish.
  • A project named "AppBlade Framework" will now be in your Package Explorer alongside your Android project.
  1. Set the AppBlade Framework to compile as a Library.
  • Right click your new "AppBlade Framework" project in the package explorer and select "Properties"
  • In the Properties window, select Android from the left navigation list.
  • Make sure the project is pointing to a valid Build Target on your machine and the Is Library check box is checked. Then hit apply.
  1. Attach the AppBlade Framework Library to your android project.
  • Right click your project in the package explorer and select "Properties"
  • In the Properties window, select Android from the left navigation list.
  • Under the Library panel, click Add... and select the AppBlade Framework project in the pop-up window.
  • The AppBlade Framework should now appear as a library for your project.
  1. Add the AppBlade Framework Dependency Library to your android project.
  • Ensure your project has a libs directory.
  • Download a copy of httpmime-4.1.2.jar (either from an apache site or on our repo ).
  • Attach httpmime-4.1.2 as you would a regular library dependency.
  1. The SDK should now be embedded! Confirm this by importing the AppBlade class in your Main Activity. (import com.appblade.framework.AppBlade;)
  2. You'll need to register the app with AppBlade before using any of its features, though. Read more on how to implement the SDK features here.

###Adding Android Binary###

  1. Add a "libs" folder to your project (if one does not already exist) and include the latest AppBlade jar file (downloadable here: SDK v0.3.0). Make sure you have the asset set to "copy"

    Make sure you have "Copy files" selected.

  2. Add a library reference to the AppBlade jar file in your project. If you are using Eclipse with the ADT plugin, you can right-click on your project file and select Properties, navigate to Java Build Path - Libraries - Add JARs _

  3. And select the AppBlade jar by browsing to the libs folder (and confirming your selection). _

  4. The SDK should now be embedded! Confirm this by importing the AppBlade class (import com.appblade.framework.AppBlade;) in your Main Activity or your custom Application class (where your api keys will be declared). _

  5. You'll need to register the app with AppBlade before using any of its features, though. Read more on how to implement the SDK features here.

###Using ProGuard###

  1. Many Android Users prefer to obfuscate their code with ProGuard. To make AppBlade work with obfuscated code, add the following to your proguard-project.txt file:

     -keep class com.appblade.** { *; }

This will allow you to use our authentication feature in a ProGuard-encoded app.

Clone this wiki locally