PeriscopeAndroid

PeriscopeAndroid captures OkHttp traffic and forwards events to a network monitor viewer.

Install

Gradle (Maven Central)

In your root settings.gradle.kts:

dependencyResolutionManagement {
    repositories {
        mavenCentral()
        google()
    }
}

In your app/module build.gradle.kts:

dependencies {
    implementation("io.github.ryanneilstroud:periscopeandroid:1.2.0")
}

Quick Start

val periscope = Periscope.default
Periscope.initialize(applicationContext) // enables network-path aware reconnect behavior
Periscope.capture(Periscope.Receiver.simulator) // uses Periscope.default

val client = OkHttpClient.Builder()
    .addInterceptor(periscope.interceptor())
    .build()

Usage

You can also create your own instance:

val periscope = Periscope()
periscope.capture(Periscope.Receiver.simulator)

For strict reconnect behavior after network-path changes, initialize with app context:

Periscope.initialize(applicationContext)

Capture transport is process-wide. If multiple Periscope instances call capture(...), only the first active capture session is applied until stop() is called.

Receiver constructors

Periscope.Receiver has static constructors:

1. Receiver.simulator for local emulator development (routes to 10.0.2.2, default port).
2. Receiver.simulator(port) for local emulator development with a custom port.
3. Receiver.device(host, port) for explicit host routing, especially physical devices.

// Local emulator development
Periscope.capture(Periscope.Receiver.simulator)

// Physical device targeting your Mac's LAN IP
Periscope.capture(Periscope.Receiver.device(host = "192.168.1.25"))

Receiver.simulator and Receiver.device(host, port) both default to port 61337.

OkHttp integration

Add the interceptor to each OkHttp client you want to monitor:

val client = OkHttpClient.Builder()
    .addInterceptor(periscope.interceptor())
    .build()

WebSocket integration (since 1.2.0)

Create OkHttp WebSockets through Periscope to capture lifecycle events and inbound/outbound text and binary messages:

val socket = periscope.newWebSocket(
    client = client,
    request = Request.Builder().url("wss://example.com/socket").build(),
    listener = object : WebSocketListener() {
        override fun onMessage(webSocket: WebSocket, text: String) {
            // Handle the message normally.
        }
    }
)

Payloads are limited to 64 KiB per event. Unlike iOS, Android requires this explicit factory because OkHttp does not provide a safe process-wide WebSocket observation hook.

Stop capture

When you need to stop forwarding events:

Periscope.stop() // stops Periscope.default

Receiver-based API (since 0.5.1)

capture(host, port) was removed in 0.5.1 in favor of the receiver-based API:

Periscope.capture(Periscope.Receiver.simulator)

If you create custom OkHttpClient instances:

val client = OkHttpClient.Builder()
    .addInterceptor(periscope.interceptor())
    .build()