Skip to main content
Version: 11.8.0

How to add and remove request and response interceptors on Android

A request interceptor runs before the player opens the connection, so it can change properties of the request such as its URL, method, headers or body. It can also respond to the request immediately, without contacting the server.

A response interceptor runs before the player consumes the response, so it can change the status, the headers or the body of the response.

Prerequisites​

This guide assumes that you already have THEOplayer set up in your app. If not, start with our getting started guide.

Adding and removing an interceptor​

The Android SDK provides the HTTPInterceptor interface, which contains two methods that you can implement depending on your use case:

  • suspend fun onRequest(request: InterceptableHTTPRequest): intercepts an HTTP request before opening the connection.
  • suspend fun onResponse(response: InterceptableHTTPResponse): intercepts an HTTP response before consuming the response body.

To start intercepting HTTP requests, add the interceptor to the Network API:

theoPlayerView.player.network.addHTTPInterceptor(httpInterceptor)

To stop intercepting HTTP requests, remove the interceptor again:

theoPlayerView.player.network.removeHTTPInterceptor(httpInterceptor)

Intercepting a request​

The request parameter of onRequest allows you to read and write properties of the request, or to interrupt the request by responding to it directly.

The snippet below shows some common use cases.

override suspend fun onRequest(request: InterceptableHTTPRequest) {
    // Read request properties
    Log.d("Interceptor", "onRequest - url: ${request.url}")

    // Add/override request headers
    request.headers["newKey"] = "newValue"

    // Replace properties
    request.method = "GET|POST|.."
    request.url = URL("new_url")
    request.headers = HashMap()

    // Replace POST/PUT request body
    request.body = "new post body".toByteArray()

    // Perform another async computation
    delay(1000) // simulating an async call

    // Interrupt the request and respond with a CompleteHTTPResponse
    request.respondWith(
        CompleteHTTPResponse(
            request,
            request.url,
            request.headers,
            200,
            "OK",
            "new post body".toByteArray()
        )
    )
}

Intercepting a response​

The response parameter of onResponse allows you to read and write properties of the received response.

The snippet below shows some common use cases.

override suspend fun onResponse(response: InterceptableHTTPResponse) {
    // Read response properties
    Log.d("Interceptor", "onResponse - headers: ${response.headers}")

    // Add/override response headers
    response.headers["newKey"] = "newValue"

    // Replace properties
    response.url = URL("new_url")
    response.headers = HashMap()
    response.status = 200
    response.statusText = "OK"

    // Get the chunks of the response body as they are read from the HTTP connection
    response.onChunk { chunk: ByteArray ->
        Log.d("Interceptor", "onResponse - onChunk: ${chunk.size}")
        delay(100)
        chunk
    }

    // Read the complete response body
    response.onBody { body: ByteArray ->
        Log.d("Interceptor", "onResponse - onBody: ${body.size}")

        // Read response body
        val string = body.decodeToString()
        val json = JSONObject(string)

        // Perform another async computation
        delay(1000) // simulating an async call

        // Replace response body
        "new response body".toByteArray()
    }
}