The Aviary SDK is now part of the Adobe Creative SDK

The Aviary SDK is now the Image Editing component in the Adobe Creative SDK. Visit CreativeSDK.com to access the latest Image Editing SDK and brand new SDK components by Adobe, offering features like store to Creative Cloud and publish to Behance.

Aviary SDK Setup Guide

Revision 3.6.3

This document will guide you through the creation of a sample application using the Aviary SDK Android library.

Table of Contents

1. Introduction

This document will guide you through the creation of a sample application using the Aviary SDK Android library.

2. Prerequisites

Before you start, be sure your you have the following prerequisites:

  • You need your Aviary api key and secret ( get this for free from aviary.com/android )
  • The Android SDK Bundle already installed and configured on your system.
  • Gradle 2.2 or higher, gradle plugin of 1.0.0-rc1 or higher, and Android build tools version 20.0.0 or higher installed on your system. These automatically installed when you install Android Studio. (You may need to update them if you installed it a long time ago) This release of the SDK was built in Android Studio 1.0 RC 2.
  • A gradle enabled Android application project. To migrate your project from Ant and Eclipse to Gradle, click here.

3. Android Versions

The Aviary Android SDK supports Android 2.3.3+ ( API Level 10 ) as the minSdkVersion, but it must be compiled using Android 4.4 ( API Level 20 ) as the targetSdkVersion.

4. Workspace Setup

4.1 Project setup without adding the SDK as a module

With Gradle, setting up with Aviary is extremely simple. Follow this approach only if you do not plan on customizing the SDK. Otherwise, you will need to add the SDK as its own module in your project directory. See section 4.2 for an in-depth walkthrough of this.

To start, open the build.gradle file of your Application in Android Studio. Please note that this is different from the build.gradle file of your root project.

Make sure that in the repositories block, you have both Maven Central and Aviary's Maven repository. It should look something like this:

repositories {
    mavenCentral()
    jcenter()
    mavenLocal()
    maven {
        name 'maven.aviary.com'
        url uri("http://maven.aviary.com/repo/release")
    }
}

In this same file, add the following to the dependencies block in order to build your project with the Aviary SDK:

compile 'com.aviary.android.feather.sdk:aviary-sdk:3.6.3'

Finally, within packagingOptions in the android block, add the following in order to prevent duplicate copying of these files:

exclude 'META-INF/NOTICE.txt'
exclude 'META-INF/LICENSE.txt'

Here is an example how the build.gradle file should look:

apply plugin: 'com.android.application'

repositories {
    mavenCentral()
    jcenter()
    mavenLocal()
    maven {
        name 'maven.aviary.com'
        url uri("http://maven.aviary.com/repo/release")
    }
}

android {
    compileSdkVersion 20
    buildToolsVersion "20.0.0"

    defaultConfig {
        minSdkVersion 10
        targetSdkVersion 20
        versionCode 1
        versionName "1.0"
    }

    buildTypes {
        release {
          minifyEnabled false
          proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }   

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_7
        targetCompatibility JavaVersion.VERSION_1_7
    }

    packagingOptions {
        exclude 'META-INF/NOTICE.txt'
        exclude 'META-INF/LICENSE.txt'
    }               

}

dependencies {
    compile 'com.aviary.android.feather.sdk:aviary-sdk:3.6.3'
}

(Note that the minSdkVersion is 10.)

4.2 Project setup with Aviary-SDK as a module

This setup requires a bit more work, but will allow you to add your own customizations to the Aviary-SDK. Start by unzipping the SDK directory that you got from http://aviary.com/android.

Then drag the file called Aviary-SDK into your root project directory in Android Studio:

drag folder

Then open the file called settings.gradle in your root project and add the following line to it:

include ':Aviary-SDK'

Now go File -> Project Structure and click on the Dependencies tab. Locate the '+' near the bottom left corner of this popup and click on it, and then Module dependency from the presented options:

add module

Then select :Aviary-SDK and press OK:

drag folder

Finally, open the build.gradle file of your application (not the root build.gradle) and add the following block:

repositories {
    mavenCentral()
    jcenter()
    mavenLocal()
    maven {
        name 'maven.aviary.com'
        url uri("http://maven.aviary.com/repo/release")
    }
}

Make sure your minSdkVersion is set to at least 10:

defaultConfig {
    minSdkVersion 10
    targetSdkVersion 20
    versionCode 1
    versionName "1.0"
}

Now just sync, and you should be all setup! By the way, press this button to sync:

sync

The final file should look something like this:

apply plugin: 'com.android.application'

repositories {
    mavenCentral()
    mavenLocal()
    maven {
        name 'maven.aviary.com'
        url uri("http://maven.aviary.com/repo/release")
    }
}

android {
    compileSdkVersion 20
    buildToolsVersion "20"

    defaultConfig {
        minSdkVersion 10
        targetSdkVersion 20
        versionCode 1
        versionName "1.0"
    }

    buildTypes {
        release {
        minifyEnabled false
        proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }

    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_7
        targetCompatibility JavaVersion.VERSION_1_7
    }
}

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    compile 'com.android.support:appcompat-v7:20.+'
    compile project(':Aviary-SDK')
}

5. AndroidManifest.xml

There are some changes you need to make to your AndroidManifest.xml before you can open the Aviary Editor from your Activity.

5.1. Add the API Key

Grab your api key from http://aviary.com/android

Inside the <application> tag add a new meta-data entry like this:

        <meta-data
            android:name="com.aviary.android.feather.v1.API_KEY"
            android:value="your_api_key_here" />

Replace the tag value with your api-key.

5.2. Permissions

The Aviary-SDK requires 2 permissions: internet and write access to external storage. To grant these permissions, add these entries inside the <manifest> tag:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

An additional permission is necessary if you want to turn on vibration feedback ( some widgets inside the Aviary-SDK use the vibration feedback for a better user experience ), but the vibration is optional. If you want to enable the vibration just add this new permission inside the <manifest> tag:

<uses-permission android:name="android.permission.VIBRATE" />

5.3. Required Entries

Inside the <application> tag, add the following entries:

<!-- Main Editor Activity -->
<activity
    android:name="com.aviary.android.feather.sdk.FeatherActivity"
    android:configChanges="orientation|keyboardHidden|screenSize"
    android:screenOrientation="unspecified"
    android:hardwareAccelerated="true"
    android:largeHeap="true"
    android:process=":aviarysdk"
    android:theme="@style/AviaryTheme.Dark" />

Note: It's important that you specify @style/AviaryTheme.Dark as default theme for the FeatherActivity.

    <!-- CDS Content Service -->
    <service
        android:process=":aviarycds"
        android:name="com.aviary.android.feather.cds.AviaryCdsService"
        android:exported="false">
        <intent-filter>
            <action android:name="aviary.intent.action.CDS_DOWNLOAD_START"/>
            <action android:name="aviary.intent.action.CDS_RESTORE_USER_ITEMS"/>
        </intent-filter>
    </service> 

    <!-- 
        Cds Content Provider, 
        NOTE that the "authorities" value MUST be formatted in this way:
        android:authorities="{your.packagename}.AviaryCdsProvider"
     -->
    <provider
        android:name="com.aviary.android.feather.cds.AviaryCdsProvider"
        android:authorities="{your.package.name}.AviaryCdsProvider"
        android:process=":aviarycds"
        android:exported="false"
        android:syncable="true" />  

Note: it's important that the AviaryCdsProvider entry has the field android:authorities with the value {your.package.name}.AviaryCdsProvider where you have to replace {your.package.name} with the same package name defined in your AndroidManifest.xml in the <manifest> tag.

    <!-- CDS Download Receiver -->
    <receiver 
        android:name="com.aviary.android.feather.cds.AviaryCdsReceiver"
        android:process=":aviarycds" >
        <intent-filter>
            <action android:name="android.intent.action.DOWNLOAD_COMPLETE" />
        </intent-filter>
    </receiver>

6. Invoke the Aviary Editor

To invoke Aviary from your activity, all you need to do is create this Intent:

Intent newIntent = new Intent( this, FeatherActivity.class );
newIntent.setData( Uri.parse("content://media/external/images/media/32705") );
newIntent.putExtra( Constants.EXTRA_IN_API_KEY_SECRET, "your api secret" );
startActivityForResult( newIntent, 1 );    

This is the minimum required Intent you need to use in order to open the Aviary SDK.
The image Uri is mandatory and it can have the following scheme:

  • ContentResolver.SCHEME_FILE: absolute local file path ( "file:///mnt/sdcard/download/image.jpg" )
  • No scheme: absolute local file path ( "/mnt/sdcard/bla/image.jpg" )
  • ContentResolver.SCHEME_CONTENT: database driven file location ( "content://media/external/images/media/112232" )
  • "http" or "https": remote files.

Also the api key secret is required.

There are many other (optional) parameters supported by the FeatherActivity class. You can read more about them in the INTENT_PARAMETERS.html document

6.1. Result parameters

Once the user clicks "Done" (save) in the FeatherActivity, the onActivityResult of your Activity will be invoked, passing back the action code as requestCode (for more information, read here). The Uri data of the returned intent will be the path of the output image:

@Override
public void onActivityResult( int requestCode, int resultCode, Intent data ) {
    if( resultCode == RESULT_OK ) {
        switch( requestCode ) {
            case 1:
                // output image path
                Uri mImageUri = data.getData();
                Bundle extra = data.getExtras();
                    if( null != extra ) {
                        // image has been changed by the user?
                        boolean changed = extra.getBoolean( Constants.EXTRA_OUT_BITMAP_CHANGED );
                    }
                break;
        }
    }
}

Note the Constants.EXTRA_OUT_BITMAP_CHANGED. This flag will indicate whether the image has been changed by the user or they just clicked the "done" button without any modification to the Image. For more information, please read the INTENT_PARAMETERS document.

7. Proguard

If your application is compiled using proguard, you need to update your proguard-project.pro file, or whatever you have named the file containing your proguard settings. A sample file called 'proguard-rules.pro' is included in this SDK with the sample application. You must append all of the rules in it to your file, or if you do not have a file you can simply use the attached file itself.

8. High Resolution Image Editing

By default, the Aviary editor works on a medium resolution image in order to speed up the performance of the editor. In fact, the image returned in your onActivityResult will have, more or less, the same size of the device screen pixels. If you want to save the edited images in high resolution, you must pass an extra parameter to FeatherActivity when you start it:

newIntent.putExtra( Constants.EXTRA_IN_HIRES_MEGAPIXELS, MegaPixels.Mp5.ordinal() );

The second parameter is the maximum number of megapixels you would like the hires processing to work on. You can post process images from 3MP up to 30MP (megapixels).

9. Custom Exif Tags

By default all tags of an image are preserved. In addition to this, you can save custom exif tags by extending the FeatherActivity class and overriding the method onSaveCustomTags. Save your custom tag into the ExifInterface which is provided as an argument in the method. So, if you would like to save a custom artist, do the following in onSaveCustomTags:

exif.buildTag( ExifInterface.TAG_ARTIST, artist_name );

10. Customization

You can customize almost all the visual aspects of the Aviary UI by editing the style entries (aviary_styles.xml), colors (aviary_colors.xml), dimensions (aviary_dimens.xml).

Most of the custom attributes you'll find inside the aviary_theme.xml and aviary_styles.xml files are documented inside the aviary_attrs.xml file.

The aviary_config.xml file contains all the customizable behaviors of the SDK, like the colors to show inside the text tool or the drawing tool, the sizes of the brush tools, the custom crop ratios for the crop tool, the default font used in the meme tool, etc..

Inside the aviary_config.xml file you'll find a detailed description of every entry.

11. Using Aviary without the SDK

You can still use the Aviary Editor and all its features without embedding the SDK inside your application. You just need to check if the Aviary Editor is installed on the user device. To do this use the following snippet:

public boolean isAviaryInstalled(){
    Intent intent = new Intent( "aviary.intent.action.EDIT" );
    intent.setType( "image/*" );
    List<ResolveInfo> list = getPackageManager()
        .queryIntentActivities( intent, PackageManager.MATCH_DEFAULT_ONLY );  
    return list.size() > 0; 
}

If Aviary is not installed then you can prompt your user to download the application from the Google play store using this Intent:

Intent intent = new Intent( Intent.ACTION_VIEW );
intent.setData( Uri.parse( "market://details?id=com.aviary.android.feather" ) );
startActivity( intent );

Once the Editor is installed on the user's device, you can start the Aviary Editor using this Intent:

Intent newIntent = new Intent( "aviary.intent.action.EDIT" );
newIntent.setDataAndType( uri, "image/*" ); // required
newIntent.putExtra( "app-id", getPackageName() ); // required ( it's your app unique package name )

As you can see the Intent is slightly different from the one used previously (using the embedded Aviary-SDK), but all the extras supported by the FeatherActivity Intent are still valid.

12. Sample Application

If you have problems including the Aviary-SDK within your application, you can checkout our Sample Application, which includes all the features described here.

Note: The Sample application does not include the Aviary API Key, so you need to edit its AndroidManifest.xml file in order to run the application, as described in the Add the API Key chapter. You will also need to add your API-secret in the MainActivity and your public Google Play billing key for in-app purchases.

Aviary SDK Setup Guide

Revision 3.6.3

This document will guide you through the creation of a sample application using the Aviary SDK Android library.

Table of Contents

1. Introduction

This document will guide you through the creation of a sample application using the Aviary SDK Android library.

2. Prerequisites

Before you start, be sure your you have the following prerequisites:

  • You need your Aviary api key and secret ( get this for free from aviary.com/android )
  • The Android SDK Bundle already installed and configured on your system.
  • Eclipse with the Android Developer Tools plugin, see here

3. Android Versions

The Aviary Android SDK supports Android 2.3.3+ ( API Level 10 ) as the minSdkVersion, but it must be compiled using Android 4.4 ( API Level 20 ) as the targetSdkVersion.

4. Workspace Setup

Open Eclipse and from the menu/file command select "Import…"

import project in eclipse

The import dialog will appear. From the list of import options, select "Existing Android Code into Workspace," and then click "Next."

import project in eclipse

You then need to import the following projects:

import project in eclipse

Click on the "Finish" button at the bottom of the dialog. A new Android library project called Aviary-SDK will be created in your current workspace. This is the required library project which you must include in your application if you want to use Aviary to manipulate images.

Note that the Aviary-SDK is dependent on two other projects, HorizontalListView and TooltipManager.

In order to load the default effects in your editor, copy the contents of the assets folder in Aviary-SDK into the assets folder of your application.

5. AndroidManifest.xml

There are some changes you need to make to your AndroidManifest.xml before you can open the Aviary Editor from your Activity.

As mentioned above, the Aviary-SDK supports Android 2.3.3+ (API Level 10) as the minimum Android version, so the <uses-sdk> node of your manifest should look like this:

<uses-sdk
    android:minSdkVersion="10"
    android:targetSdkVersion="20" />

5.1. Add the API Key

Grab your api key from https://developers.aviary.com/apps

Inside the <application> tag add a new meta-data entry like this:

        <meta-data
            android:name="com.aviary.android.feather.v1.API_KEY"
            android:value="your_api_key_here" />

Replace the tag value with your api-key.

5.2. Permissions

The Aviary-SDK requires 2 permissions: internet and write access to external storage. To grant these permissions, add these entries inside the <manifest> tag:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

An additional permission is necessary if you want to turn on vibration feedback ( some widgets inside the Aviary-SDK use the vibration feedback for a better user experience ), but the vibration is optional. If you want to enable the vibration just add this new permission inside the <manifest> tag:

<uses-permission android:name="android.permission.VIBRATE" />

5.3. Required Entries

Inside the <application> tag, add the following entries:

<!-- Main Editor Activity -->
<activity
    android:name="com.aviary.android.feather.sdk.FeatherActivity"
    android:configChanges="orientation|keyboardHidden|screenSize"
    android:screenOrientation="unspecified"
    android:hardwareAccelerated="true"
    android:largeHeap="true"
    android:process=":aviarysdk"
    android:theme="@style/AviaryTheme.Dark" />

Note: It's important that you specify @style/AviaryTheme.Dark as default theme for the FeatherActivity.

    <!-- CDS Content Service -->
    <service
        android:process=":aviarycds"
        android:name="com.aviary.android.feather.cds.AviaryCdsService"
        android:exported="false">
        <intent-filter>
            <action android:name="aviary.intent.action.CDS_DOWNLOAD_START"/>
            <action android:name="aviary.intent.action.CDS_RESTORE_USER_ITEMS"/>
        </intent-filter>
    </service> 

    <!-- 
        Cds Content Provider, 
        NOTE that the "authorities" value MUST be formatted in this way:
        android:authorities="{your.packagename}.AviaryCdsProvider"
     -->
    <provider
        android:name="com.aviary.android.feather.cds.AviaryCdsProvider"
        android:authorities="{your.package.name}.AviaryCdsProvider"
        android:process=":aviarycds"
        android:exported="false"
        android:syncable="true" />  

Note: it's important that the AviaryCdsProvider entry has the field android:authorities with the value {your.package.name}.AviaryCdsProvider where you have to replace {your.package.name} with the same package name defined in your AndroidManifest.xml in the <manifest> tag.

    <!-- CDS Download Receiver -->
    <receiver 
        android:name="com.aviary.android.feather.cds.AviaryCdsReceiver"
        android:process=":aviarycds" >
        <intent-filter>
            <action android:name="android.intent.action.DOWNLOAD_COMPLETE" />
        </intent-filter>
    </receiver>

6. Invoke the Aviary Editor

To invoke Aviary from your activity, all you need to do is create this Intent:

Intent newIntent = new Intent( this, FeatherActivity.class );
newIntent.setData( Uri.parse("content://media/external/images/media/32705") );
newIntent.putExtra( Constants.EXTRA_IN_API_KEY_SECRET, "your api secret" );
startActivityForResult( newIntent, 1 );    

This is the minimum required Intent you need to use in order to open the Aviary SDK.
The image Uri is mandatory and it can have the following scheme:

  • ContentResolver.SCHEME_FILE: absolute local file path ( "file:///mnt/sdcard/download/image.jpg" )
  • No scheme: absolute local file path ( "/mnt/sdcard/bla/image.jpg" )
  • ContentResolver.SCHEME_CONTENT: database driven file location ( "content://media/external/images/media/112232" )
  • "http" or "https": remote files.

Also the api key secret is required.

There are many other (optional) parameters supported by the FeatherActivity class. You can read more about them in the INTENT_PARAMETERS.html document

6.1. Result parameters

Once the user clicks "Done" (save) in the FeatherActivity, the onActivityResult of your Activity will be invoked, passing back the action code as requestCode (for more information, read here). The Uri data of the returned intent will be the path of the output image:

@Override
public void onActivityResult( int requestCode, int resultCode, Intent data ) {
    if( resultCode == RESULT_OK ) {
        switch( requestCode ) {
            case 1:
                // output image path
                Uri mImageUri = data.getData();
                Bundle extra = data.getExtras();
                    if( null != extra ) {
                        // image has been changed by the user?
                        boolean changed = extra.getBoolean( Constants.EXTRA_OUT_BITMAP_CHANGED );
                    }
                break;
        }
    }
}

Note the Constants.EXTRA_OUT_BITMAP_CHANGED. This flag will indicate whether the image has been changed by the user or they just clicked the "done" button without any modification to the Image. For more information, please read the INTENT_PARAMETERS document.

7. Proguard

If your application is compiled using proguard, you need to update your proguard-project.txt file, or whatever you have named the file containing your proguard settings. A sample file called 'proguard-rules.pro' is included in this SDK. You must append all of the rules in it to your file, or if you do not have a file you can simply use the attached file itself.

8. High Resolution Image Editing

By default, the Aviary editor works on a medium resolution image in order to speed up the performance of the editor. In fact, the image returned in your onActivityResult will have, more or less, the same size of the device screen pixels. If you want to save the edited images in high resolution, you must pass an extra parameter to FeatherActivity when you start it:

newIntent.putExtra( Constants.EXTRA_
IN_HIRES_MEGAPIXELS, MegaPixels.Mp5.ordinal() );

The second parameter is the maximum number of megapixels you would like the hires processing to work on. You can post process images from 3MP up to 30MP (megapixels). If you want to save the edited images in high resolution, read the High Resolution document.

9. Custom Exif Tags

By default all tags of an image are preserved. In addition to this, you can save custom exif tags by extending the FeatherActivity class and overriding the method onSaveCustomTags. Save your custom tag into the ExifInterface which is provided as an argument in the method. So, if you would like to save a custom artist, do the following in onSaveCustomTags:

exif.buildTag( ExifInterface.TAG_ARTIST, artist_name );

10. Customization

You can customize almost all the visual aspects of the Aviary UI by editing the style entries (aviary_styles.xml), colors (aviary_colors.xml), dimensions (aviary_dimens.xml).

Most of the custom attributes you'll find inside the aviary_theme.xml and aviary_styles.xml files are documented inside the aviary_attrs.xml file.

The aviary_config.xml file contains all the customizable behaviors of the SDK, like the colors to show inside the text tool or the drawing tool, the sizes of the brush tools, the custom crop ratios for the crop tool, the default font used in the meme tool, etc..

Inside the aviary_config.xml file you'll find a detailed description of every entry.

11. Using Aviary without the SDK

You can still use the Aviary Editor and all its features without embedding the SDK inside your application. You just need to check if the Aviary Editor is installed on the user device. To do this use the following snippet:

public boolean isAviaryInstalled(){
    Intent intent = new Intent( "aviary.intent.action.EDIT" );
    intent.setType( "image/*" );
    List<ResolveInfo> list = getPackageManager()
        .queryIntentActivities( intent, PackageManager.MATCH_DEFAULT_ONLY );  
    return list.size() > 0; 
}

If Aviary is not installed then you can prompt your user to download the application from the Google play store using this Intent:

Intent intent = new Intent( Intent.ACTION_VIEW );
intent.setData( Uri.parse( "market://details?id=com.aviary.android.feather" ) );
startActivity( intent );

Once the Editor is installed on the user's device, you can start the Aviary Editor using this Intent:

Intent newIntent = new Intent( "aviary.intent.action.EDIT" );
newIntent.setDataAndType( uri, "image/*" ); // required
newIntent.putExtra( "app-id", getPackageName() ); // required ( it's your app unique package name )

As you can see the Intent is slightly different from the one used previously (using the embedded Aviary-SDK), but all the extras supported by the FeatherActivity Intent are still valid.

12. Sample Application

If you have problems including the Aviary-SDK within your application, you can checkout our Sample Application, which includes all the features described here.

Note: The Sample application does not include the Aviary API Key, so you need to edit its AndroidManifest.xml file in order to run the application, as described in the Add the API Key chapter. You will also need to add your API-secret in the MainActivity and your public Google Play billing key if you are in the Partner Content Network.