Set up resumable uploads for Android

The FastPix Android Resumable Uploads SDK helps you efficiently upload large files from the browser by splitting them into chunks and also gives you the ability to pause and resume your uploads.

Step 1: Install the Android SDK

Add our repository to your Gradle project

maven(url ="https://maven.pkg.github.com/FastPix/android-uploads-sdk") { 
            credentials { 
                username = "your_gihub_username" 
                password = "your_github_personal_token" 
            } 
        } 

maven { 
    url "https://maven.pkg.github.com/FastPix/android-uploads-sdk" 
    credentials { 
        username = "your_gihub_username" 
        password = "your_github_personal_token" 
    } 
} 

Add the dependency to your app

Add Fastpix’s library to the dependencies block of your app in module level build.gradle file.

dependencies { 
    implementation("io.fastpix:uploads:1.0.1")    
} 

dependencies { 
    implementation 'io.fastpix:uploads:1.0.1' 
} 

Step 2: Create an upload URL

In order to upload a video, you will need a signed upload URL.

To get this signed URL, you’ll need a valid Access Token and Secret Key. See the Authentication Guide for details on retrieving these credentials.

After obtaining your credentials, the next step is to generate a signed URL by calling the Upload Media from Device API. Once you have the signed URL, you’re all set to move forward with integrating the SDK into your app.

The example below demonstrates how to retrieve a signed URL using the Upload Media from Device API. You can either use this example directly or refer to our guide on uploading videos directly for more details.

private fun getSignedUrl() { 
    val client = OkHttpClient() 
    val mediaType = "application/json; charset=utf-8".toMediaType() 
    // Construct JSON body using JSONObject 
    val requestBodyJson = JSONObject().apply { 
        put("corsOrigin", "*") 
        put("pushMediaSettings", JSONObject().apply { 
            put("metadata", JSONObject().apply { 
                put("key1", "value1") 
            }) 
            put("accessPolicy", "public") 
            put("maxResolution", "1080p")
            put("mediaQuality", "standard") 
        }) 
    } 
    val requestBody = requestBodyJson.toString().toRequestBody(mediaType) 
    // Create Authorization header 
    val credentials = "$tokenId:$secretKey" 
    val auth = "Basic " + Base64.encodeToString(credentials.toByteArray(), Base64.NO_WRAP) 
    // Build the HTTP request 
    val request = Request.Builder() 
        .url("https://api.fastpix.com/v1/on-demand/upload") 
        .addHeader("Authorization", auth) 
        .addHeader("Content-Type", "application/json") 
        .post(requestBody) 
        .build() 
    // Execute request 
    client.newCall(request).enqueue(object : Callback { 
        override fun onFailure(call: Call, e: IOException) { 
            LOGGER.log(Level.SEVERE, e.message) 
        } 
        override fun onResponse(call: Call, response: Response) { 
            if (response.isSuccessful) { 
                response.body?.string()?.let { 
                    val jsonObject = JSONObject(it) 
                    val jsonData = jsonObject.getJSONObject("data") 
                    val signedUrl = jsonData.getString("url") 
 
                    // TODO: use signedUrl and uploadId as needed 
                } 
            } else { 
                LOGGER.log(Level.SEVERE, "Upload URL request failed: ${response.code}") 
            } 
        } 
    }) 
} 

private void getSignedUrl() { 
    OkHttpClient client = new OkHttpClient(); 
 
    // Construct JSON body using JSONObject 
    JSONObject metadata = new JSONObject(); 
    JSONObject pushMediaSettings = new JSONObject(); 
    JSONObject requestBodyJson = new JSONObject(); 
 
    try { 
        metadata.put("key1", "value1"); 
        pushMediaSettings.put("metadata", metadata); 
        pushMediaSettings.put("accessPolicy", "public"); 
        pushMediaSettings.put("maxResolution", "1080p");
        pushMediaSettings.put("mediaQuality", "standard"); 
 
 
        requestBodyJson.put("corsOrigin", "*"); 
        requestBodyJson.put("pushMediaSettings", pushMediaSettings); 
    } catch (JSONException e) { 
        e.printStackTrace(); 
        return; 
    } 
 
    MediaType mediaType = MediaType.parse("application/json; charset=utf-8"); 
    RequestBody requestBody = RequestBody.create(requestBodyJson.toString(), mediaType); 
 
    // Create Authorization header 
    String credentials = tokenId + ":" + secretKey; 
    String auth = "Basic " + Base64.encodeToString(credentials.getBytes(StandardCharsets.UTF_8), Base64.NO_WRAP); 
 
    // Build the request 
    Request request = new Request.Builder() 
            .url("https://api.fastpix.com/v1/on-demand/upload") 
            .addHeader("Authorization", auth) 
            .addHeader("Content-Type", "application/json") 
            .post(requestBody) 
            .build(); 
 
    // Execute the request 
    client.newCall(request).enqueue(new Callback() { 
        @Override 
        public void onFailure(@NonNull Call call, @NonNull IOException e) { 
            Log.e("UPLOAD", "Failed to get signed URL", e); 
        } 
 
        @Override 
        public void onResponse(@NonNull Call call, @NonNull Response response) throws IOException { 
            if (response.isSuccessful()) { 
                String responseBody = response.body() != null ? response.body().string() : null; 
                if (responseBody != null) { 
                    try { 
                        JSONObject jsonObject = new JSONObject(responseBody); 
                        JSONObject jsonData = jsonObject.getJSONObject("data"); 
                        String signedUrl = jsonData.getString("url"); 
                        String uploadId = jsonData.getString("uploadId"); 
 
                        // TODO: use signedUrl and uploadId as needed 
 
                    } catch (JSONException e) { 
                        Log.e("UPLOAD", "Failed to parse response", e); 
                    } 
                } 
            } else { 
                Log.e("UPLOAD", "Upload URL request failed: " + response.code()); 
            } 
        } 
    }); 
} 

PLEASE NOTE

When making Basic Auth API calls, securely retrieve the username and password from environment variables (.env) or a protected server endpoint to prevent unauthorized access.

In the API response, you will get a signed URL upon successful API request. Next step is to take the signed URL and pass it to the SDK.

Step 3: Start your upload

To perform the upload from your Android app, you can use the FastPixUploadSdk class. At the simplest, you need to build your FastPixUploadSdk via its Builder, then add your listeners and start() the upload.

val sdk = FastPixUploadSdk.Builder(this) 
    .setFile(file) 
    .setSignedUrl(signedUrl) 
    .setChunkSize(chunkSize * 1024 * 1024) 
    .build() 
sdk.startUpload() 

FastPixUploadSdk sdk = new FastPixUploadSdk.Builder(this) 
        .setFile(file) 
        .setSignedUrl(signedUrl) 
        .setChunkSize(chunkSize * 1024 * 1024) 
        .build(); 
sdk.startUpload(); 

Parameters to use:

This SDK supports the following parameters

Monitor the upload progress through lifecycle events

Using the following lifecycle events lets you to build a robust and user-friendly upload experience. By tracking progress in real-time, handling errors proactively, managing chunk retries, and responding to network changes, you can ensure seamless and efficient uploads.

Integrating these event handlers into your application can enhance reliability, optimize performance, and provide users with clear, actionable feedback throughout the upload process.

class MyUploadCallback : FastPixUploadCallbacks { 
 
    override fun onProgressUpdate(progress: Double) { 
        // Called periodically to report upload progress (0.0 - 100.0) 
        // Example: update a progress bar 
    } 
 
    override fun onSuccess(timiMillis: Long) { 
        // Called when the upload completes successfully 
        // timiMillis indicates how long the upload took 
    } 
 
    override fun onError(error: String, timiMillis: Long) { 
        // Called when an error occurs during upload 
        // error provides the error message 
        // timiMillis indicates how long the upload lasted before failing 
    } 
 
    override fun onNetworkStateChange(isOnline: Boolean) { 
        // Called when the network connectivity changes 
        // isOnline indicates whether the device is currently online or offline 
    } 
 
    override fun onUploadInit() { 
        // Called when the upload process is initialized 
        // Use this to show an initial loading state or setup UI 
    } 
 
    override fun onAbort() { 
        // Called when the upload is manually aborted 
        // Use this to clean up UI or notify the user 
    } 
 
    override fun onChunkHandled( 
        totalChunks: Int, 
        filSizeInBytes: Long, 
        currentChunk: Int, 
        currentChunkSizeInBytes: Long 
    ) { 
        // Called after a chunk is successfully uploaded 
        // totalChunks: total number of chunks to upload 
        // filSizeInBytes: total file size 
        // currentChunk: index of the currently uploaded chunk 
        // currentChunkSizeInBytes: size of the uploaded chunk 
    } 
 
    override fun onChunkUploadingFailed( 
        failedChunkRetries: Int, 
        chunkCount: Int, 
        chunkSize: Long 
    ) { 
        // Called when a chunk fails to upload after retry attempts 
        // failedChunkRetries: number of retries attempted for the chunk 
        // chunkCount: index of the failed chunk 
        // chunkSize: size of the failed chunk 
    } 
 
    override fun onPauseUploading() { 
        // Called when the upload is paused 
        // Use this to reflect paused state in UI 
    } 
 
    override fun onResumeUploading() { 
        // Called when the upload resumes after being paused 
        // Use this to resume UI indicators or timers 
    } 
}

public class MyUploadCallback implements FastPixUploadCallbacks { 
 
    @Override 
    public void onProgressUpdate(double progress) { 
        // Called periodically to report upload progress (0.0 - 100.0) 
        // Example: update a progress bar 
    } 
 
    @Override 
    public void onSuccess(long timiMillis) { 
        // Called when the upload completes successfully 
        // timiMillis indicates how long the upload took 
    } 
 
    @Override 
    public void onError(String error, long timiMillis) { 
        // Called when an error occurs during upload 
        // error provides the error message 
        // timiMillis indicates how long the upload lasted before failing 
    } 
 
    @Override 
    public void onNetworkStateChange(boolean isOnline) { 
        // Called when the network connectivity changes 
        // isOnline indicates whether the device is currently online or offline 
    } 
 
    @Override 
    public void onUploadInit() { 
        // Called when the upload process is initialized 
        // Use this to show an initial loading state or setup UI 
    } 
 
    @Override 
    public void onAbort() { 
        // Called when the upload is manually aborted 
        // Use this to clean up UI or notify the user 
    } 
 
    @Override 
    public void onChunkHandled(int totalChunks, long filSizeInBytes, int currentChunk, long currentChunkSizeInBytes) { 
        // Called after a chunk is successfully uploaded 
        // totalChunks: total number of chunks to upload 
        // filSizeInBytes: total file size 
        // currentChunk: index of the currently uploaded chunk 
        // currentChunkSizeInBytes: size of the uploaded chunk 
    } 
 
    @Override 
    public void onChunkUploadingFailed(int failedChunkRetries, int chunkCount, long chunkSize) { 
        // Called when a chunk fails to upload after retry attempts 
        // failedChunkRetries: number of retries attempted for the chunk 
        // chunkCount: index of the failed chunk 
        // chunkSize: size of the failed chunk 
    } 
 
    @Override 
    public void onPauseUploading() { 
        // Called when the upload is paused 
        // Use this to reflect paused state in UI 
    } 
 
    @Override 
    public void onResumeUploading() { 
        // Called when the upload resumes after being paused 
        // Use this to resume UI indicators or timers 
    } 
} 

Manage video uploads

You can control the upload lifecycle with the following methods:

Pause an upload:

sdk.pauseUploading()

Resume an upload:

sdk.resumeUploading() 

Abort an upload:

sdk.abort() 

Usage example of Android uploads SDK

The following examples give an overview of integrating the FastPix Android Uploads SDK into your project, enabling you to build a fully customized upload interface. By making use of the SDK’s lifecycle events and configurable attributes, you can enhance functionality and optimize the upload experience.

class UploadActivity : AppCompatActivity(), FastPixUploadCallbacks { 
 
    private lateinit var sdk: FastPixUploadSdk 
 
    override fun onCreate(savedInstanceState: Bundle?) { 
        super.onCreate(savedInstanceState) 
 
        val file = File(filesDir, "your-video.mp4") 
        val signedUrl = "https://your-signed-upload-url" // Replace with actual signed URL 
        val chunkSize = 5 // Chunk size in MB 
 
        sdk = FastPixUploadSdk.Builder(this) 
            .setFile(file) 
            .setSignedUrl(signedUrl) 
            .setChunkSize(chunkSize * 1024 * 1024) // Convert MB to bytes 
            .setMaxRetries(3) // Optional: Number of retries for failed chunks 
            .setRetryDelay(2000) // Optional: Delay between retries in milliseconds 
            .callback(this) // Set this activity as the callback handler 
            .build() 
 
        sdk.startUpload() // Start the upload 
    } 
 
    // === FastPixUploadCallbacks Implementation === 
 
    override fun onProgressUpdate(progress: Double) { 
        // Called periodically to report upload progress (0.0 - 100.0) 
        Log.d("Upload", "Progress: $progress%") 
    } 
 
    override fun onSuccess(timiMillis: Long) { 
        // Called when the upload completes successfully 
        Log.d("Upload", "Upload completed in $timiMillis ms") 
    } 
 
    override fun onError(error: String, timiMillis: Long) { 
        // Called when an error occurs during upload 
        Log.e("Upload", "Error: $error after $timiMillis ms") 
    } 
 
    override fun onNetworkStateChange(isOnline: Boolean) { 
        // Called when the network connectivity changes 
        Log.d("Upload", if (isOnline) "Back online" else "Offline") 
    } 
 
    override fun onUploadInit() { 
        // Called when the upload process is initialized 
        Log.d("Upload", "Upload initialized") 
    } 
 
    override fun onAbort() { 
        // Called when the upload is manually aborted 
        Log.d("Upload", "Upload aborted by user") 
    } 
 
    override fun onChunkHandled( 
        totalChunks: Int, 
        filSizeInBytes: Long, 
        currentChunk: Int, 
        currentChunkSizeInBytes: Long 
    ) { 
        // Called after a chunk is successfully uploaded 
        Log.d("Upload", "Uploaded chunk $currentChunk/$totalChunks") 
    } 
 
    override fun onChunkUploadingFailed( 
        failedChunkRetries: Int, 
        chunkCount: Int, 
        chunkSize: Long 
    ) { 
        // Called when a chunk fails after all retry attempts 
        Log.e("Upload", "Chunk $chunkCount failed after $failedChunkRetries retries") 
    } 
 
    override fun onPauseUploading() { 
        // Called when the upload is paused 
        Log.d("Upload", "Upload paused") 
    } 
 
    override fun onResumeUploading() { 
        // Called when the upload resumes 
        Log.d("Upload", "Upload resumed") 
    } 
} 

class UploadActivity : AppCompatActivity(), FastPixUploadCallbacks { 
 
    private lateinit var sdk: FastPixUploadSdk 
 
    override fun onCreate(savedInstanceState: Bundle?) { 
        super.onCreate(savedInstanceState) 
 
        val file = File(filesDir, "your-video.mp4") 
        val signedUrl = "https://your-signed-upload-url" // Replace with actual signed URL 
        val chunkSize = 5 // Chunk size in MB 
 
        sdk = FastPixUploadSdk.Builder(this) 
            .setFile(file) 
            .setSignedUrl(signedUrl) 
            .setChunkSize(chunkSize * 1024 * 1024) // Convert MB to bytes 
            .setMaxRetries(3) // Optional: Number of retries for failed chunks 
            .setRetryDelay(2000) // Optional: Delay between retries in milliseconds 
            .callback(this) // Set this activity as the callback handler 
            .build() 
 
        sdk.startUpload() // Start the upload 
    } 
 
    // === FastPixUploadCallbacks Implementation === 
 
    override fun onProgressUpdate(progress: Double) { 
        // Called periodically to report upload progress (0.0 - 100.0) 
        Log.d("Upload", "Progress: $progress%") 
    } 
 
    override fun onSuccess(timiMillis: Long) { 
        // Called when the upload completes successfully 
        Log.d("Upload", "Upload completed in $timiMillis ms") 
    } 
 
    override fun onError(error: String, timiMillis: Long) { 
        // Called when an error occurs during upload 
        Log.e("Upload", "Error: $error after $timiMillis ms") 
    } 
 
    override fun onNetworkStateChange(isOnline: Boolean) { 
        // Called when the network connectivity changes 
        Log.d("Upload", if (isOnline) "Back online" else "Offline") 
    } 
 
    override fun onUploadInit() { 
        // Called when the upload process is initialized 
        Log.d("Upload", "Upload initialized") 
    } 
 
    override fun onAbort() { 
        // Called when the upload is manually aborted 
        Log.d("Upload", "Upload aborted by user") 
    } 
 
    override fun onChunkHandled( 
        totalChunks: Int, 
        filSizeInBytes: Long, 
        currentChunk: Int, 
        currentChunkSizeInBytes: Long 
    ) { 
        // Called after a chunk is successfully uploaded 
        Log.d("Upload", "Uploaded chunk $currentChunk/$totalChunks") 
    } 
 
    override fun onChunkUploadingFailed( 
        failedChunkRetries: Int, 
        chunkCount: Int, 
        chunkSize: Long 
    ) { 
        // Called when a chunk fails after all retry attempts 
        Log.e("Upload", "Chunk $chunkCount failed after $failedChunkRetries retries") 
    } 
 
    override fun onPauseUploading() { 
        // Called when the upload is paused 
        Log.d("Upload", "Upload paused") 
    } 
 
    override fun onResumeUploading() { 
        // Called when the upload resumes 
        Log.d("Upload", "Upload resumed") 
    } 
} 

Changelog

All notable changes to the Upload SDK for android will be documented below.

Current version

[2.0.0]

A full rewrite of the upload engine for spec-compliant, production-grade GCS resumable uploads. Breaking: the public API has changed — see the migration table in the README.

Added

• New public API under io.fastpix.uploads:
  • FastPixUploader (replaces FastPixUploadSdk) with a fluent Builder and start() / pause() / resume() / cancel() methods.
  • UploadListener (replaces FastPixUploadCallbacks) with no-op defaults — override only what you need. New callbacks: onStateChange(UploadState), onPrepared(...), onChunkUploaded(...), onRetryScheduled(...), onCancelled(...).
  • UploadState enum (IDLE, PREPARING, UPLOADING, PAUSED, RETRYING, NETWORK_LOST, QUERYING_STATUS, COMPLETED, FAILED, CANCELLED) for explicit lifecycle modelling.
  • UploadError sealed class with typed variants: InvalidConfiguration, FileNotFound, FileNotReadable, FileEmpty, FileReadFailure, NetworkFailure, SessionExpired (HTTP 410), ClientError(code), ServerError(code), RetryLimitExceeded, UnexpectedResponse.
• GCS spec compliance:
  • Chunk PUTs with Content-Range: bytes start-end/total; non-final chunk size enforced as a multiple of 256 KiB at build time.
  • Server-authoritative resume: parses the Range header from 308 Resume Incomplete and resumes from last + 1. Handles 308 without a Range header (resume from byte 0) per spec.
  • Always issues a status query (PUT with Content-Range: bytes */TOTAL, empty body) before resuming after pause, network loss, or transient failure — never assumes how much the server has.
  • HTTP 410 → UploadError.SessionExpired. Retryable: 408, 429, 5xx. Fatal: other 4xx.
• Smooth, monotonic progress. Updates fire as each chunk streams (no longer only at chunk boundaries), throttled to one event per integer-percent change. A CAS-guarded high-water mark ensures progress never regresses on retry.
• Explicit upload state machine with validated transitions. Structurally impossible to send a chunk PUT after pause/retry/network-loss without first going through QUERYING_STATUS.
• Single-threaded engine. All state mutations serialised on one executor; OkHttp callbacks, network events, consumer commands, and retry timers all funnel through it. No race conditions.
• Multi-transport network awareness. Tracks the active set of networks with INTERNET capability; only signals offline when all transports drop. Transient WiFi/cellular handover events no longer trip false NETWORK_LOST.
• Configurable retry policy. Full-jitter exponential backoff (retryBaseDelay, retryMaxDelay), bounded by maxRetries.
• Main-thread callback dispatch by default. Listener calls land on the main looper; consumers no longer need runOnUiThread wrappers. Override via Builder.callbackExecutor(Executor).
• Optional HTTP logging via Builder.debugLogging(true). Off by default — release builds no longer leak signed session URIs to logcat.
• JUnit unit tests for GcsResumableProtocol, UploadStateMachine, RetryPolicy, and CallbackDispatcher (47 tests total).

Fixed

• Retries no longer silently disabled after the first successful chunk. The retry executor is now permanent for the upload’s lifetime; previously a CoroutineScope.cancel() killed it after chunk 1, causing later failures to hang forever.
• Network failures are now routed through the retry path. Previously any IOException (broken pipe, DNS hiccup, TLS reset, OkHttp cancel) terminated the upload with onError. Now classified, backed off, and resumed via status query.
• onSuccess, onFailure, and onCancelled now actually fire. A “defense in depth” terminated-flag silently dropped the terminal callback itself. Removed.
• cancel() no longer double-fires onError + onCancelled. OkHttp call cancellation is now correctly distinguished from real failures via a generation counter.
• pause() no longer leaks as onError. Intentional cancellations are detected in onFailure and suppressed.
• NetworkCallback no longer leaks across uploads. Per-uploader registration with explicit unregisterNetworkCallback on terminal.
• Working Wi-Fi no longer falsely reported as NETWORK_LOST. Dropped the NET_CAPABILITY_VALIDATED requirement, which is gated on a probe to Google’s connectivitycheck endpoint and is missing for the first few seconds of a fresh connection (and indefinitely on networks where that endpoint is blocked, e.g. corporate Wi-Fi).
• Transient losses during WiFi/cellular handover no longer trigger NETWORK_LOST. Network state is now derived from the set of matching networks; offline is signalled only when all transports drop.
• File reads no longer silently misalign on large files. RandomAccessFile.seek() replaces InputStream.skip(), which was allowed to skip fewer bytes than requested.
• OkHttp no longer silently re-PUTs bodies on connection failure. retryOnConnectionFailure(false) lets the upload engine own all retry semantics.
• Public commands after terminal state no longer crash. cancel() called twice, late OkHttp callbacks, and late connectivity events post-teardown now silently no-op instead of throwing RejectedExecutionException.

Changed

• Minimum SDK bumped from API 21 to API 24.
• Default chunk size changed from 16 MiB to 8 MiB (the GCS-recommended value).
• Method renames (see migration table in README): setSignedUrl → sessionUri, setFile → file, setChunkSize → chunkSize, setMaxRetries → maxRetries, setRetryDelay → retryBaseDelay + retryMaxDelay, callback → listener, startUpload → start, pauseUploading → pause, resumeUploading → resume, abort → cancel.
• Errors: UploadExceptions and its subclasses replaced with the UploadError sealed hierarchy.

Removed

• FastPixUploadSdk, FastPixUploadCallbacks, UploadExceptions, StreamingFileRequestBody, RetryHelper, NetworkHandler, UploadEventType.

Previous version

v1.0.1

• Implemented support for Google Cloud Storage resumable uploads and chunked client uploads.
• Added retry mechanism with exponential backoff for GCS upload failures based on retryable status codes.
• Enabled support for user-provided signed URLs, allowing resumable uploads to work with externally generated session URIs.
• Updated the API endpoint from https://v1.fastpix.io/on-demand/uploads to https://api.fastpix.com/v1/on-demand/upload for obtaining signed URLs.

v1.0.0

Features:

• Chunking: Files are automatically split into chunks (default chunk size is 16MB).
• Pause and Resume: Allows temporarily pausing the upload and resuming after a while.
• Retry: Uploads might fail due to temporary network failures. Individual chunks are retried for 5 times with exponential backoff to recover automatically from such failures.
• Lifecycle Event Listeners: Provides real-time feedback through various upload lifecycle events.
• Error Handling: Comprehensive error management to notify users of issues during uploads.
• Customizability: Options to customize chunk size and retry attempts.