Setup 3.x

Add this to your build.gradle dependencies:

def uploadServiceVersion = "3.5.2"

implementation "net.gotev:uploadservice:$uploadServiceVersion"

Initialize the library in your Application subclass:

public class Initializer extends Application {

    @Override
    public void onCreate() {
        super.onCreate();
        // setup the broadcast action namespace string which will
        // be used to notify upload status.
        // Gradle automatically generates proper variable as below.
        UploadService.NAMESPACE = BuildConfig.APPLICATION_ID;
        // Or, you can define it manually.
        UploadService.NAMESPACE = "com.yourcompany.yourapp";
    }
}

Don't forget to register it in the manifest (otherwise it won't work):

<application
    android:name=".Initializer"
    ...
    >

and now you're ready to rock! To start using the library, check the Usage instructions.

Check the minimum App example here: https://github.com/gotev/android-upload-service/releases/download/3.5.2/BasicJavaExample.zip

Continue reading below for OkHttp setup.

Upgrading from older versions

If you're upgrading from an older release:

• from 3.4 to 3.5: good news my friend, no action needed! Make sure your app supports AndroidX however.
• from 3.3 to 3.4, read 3.4 migration notes
• from 3.x to 3.3, read 3.3 migration notes
• from 2.1 to 3.0, read 3.0 migration notes
• from 1.6 to 2.1, read 2.0 migration notes
• from 1.5 to 1.6, read 1.6 migration notes

So for example if you are upgrading from 1.5 to 2.1, you have to read 1.6 and 2.0 migration notes.

OkHttp

I recommend you to also use the OkHttp stack. Add this to your dependencies:

implementation "net.gotev:uploadservice-okhttp:$uploadServiceVersion"

and then you can do the following when you perform the initialization:

// Without parameters, a new default OkHttpClient will be automatically created
UploadService.HTTP_STACK = new OkHttpStack();

// you can also pass your own OkHttp Stack as a parameter
UploadService.HTTP_STACK = new OkHttpStack(yourOkHttpClient);

uploadservice-okhttp module depends on OkHttp 3.+ Check OkHttpStack and HurlStack to see the configuration options that you have out of the box.

Here there is a complete example of OkHttp initialization with a request interceptor and logging interceptor. It's in the demo app. You can build and run it on your device.

If you want to implement your own HTTP stack, read this.

Note that starting from Android 4.4 KitKat, OkHttp is used internally to provide HttpURLConnection implementation, as reported here. The version used changes across different Android releases, so you may experience different behaviours and encounter some known bugs on older releases (e.g. #114 on Android 4.4). To avoid having to deal with that, I suggest you to switch to the OkHttp stack implementation, to be sure to have a consistent behaviour across all Android versions and to have the most updated version of OkHttp as well.

Setup Troubleshooting

Android Support Libraries version mismatch

Note: this is applicable for versions prior to 3.5.0. Newer versions depend solely on AndroidX and those problems have been solved by Google.

Android Upload Service depends on Android Support v4 and Android AppCompat v7 libraries, to guarantee compatibility for notifications across different Android versions. When your app uses different versions of the support libraries than the ones upon which Android Upload Service depends, you may encounter compilation issues. By using Gradle, there is a solution to this problem.
Example of an App which uses android support libraries 22.2.0:

apply plugin: 'com.android.application'

android {
    compileSdkVersion 22
    buildToolsVersion "21.0.0"

    defaultConfig {
        applicationId "net.gotev.testing"
        minSdkVersion 14
        targetSdkVersion 22
        versionCode 1
        versionName "1.0"
    }
    buildTypes {
        release {
            minifyEnabled false
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    testCompile 'junit:junit:4.12'
    compile 'com.android.support:appcompat-v7:22.2.0'
    compile 'com.android.support:design:22.2.0'
}

When for example you include:

compile 'net.gotev:uploadservice:2.0'

in the dependencies section and you sync your gradle file, you get something like this:

/Users/alex/workspace/Testing/app/build/intermediates/res/merged/debug/values-v23/values-v23.xml
Error:(3) Error retrieving parent for item: No resource found that matches the given name 'android:TextAppearance.Material.Widget.Button.Inverse'.
Error:(24) Error retrieving parent for item: No resource found that matches the given name 'android:Widget.Material.Button.Colored'.
Error:Execution failed for task ':app:processDebugResources'.
> com.android.ide.common.process.ProcessException: org.gradle.process.internal.ExecException: Process 'command '/Users/alex/workspace/sdk/build-tools/21.0.0/aapt'' finished with non-zero exit value 1

And then your Android Studio opens an xml file. To resolve this issue, you just need to add this in the android section of your gradle file:

configurations.all {
    resolutionStrategy {
        force 'com.android.support:support-v4:22.+'
        force 'com.android.support:appcompat-v7:22.+'
    }
}

Then sync again and the error should be resolved. Note that 22.+ has to be replaced with the version used by your app, so if you use version 21, you will have to write 21.+. If you still have build errors after this fix, check your other project dependencies to find where the problem is. Managing dependencies the right way is not a straightforward process. You have to be patient and care about every single detail, because the mess is always around the corner.