Skip to main content

Add Outline SDK to your mobile app

This document outlines how to integrate the Outline SDK into your mobile applications, focusing on the MobileProxy library for simplified local proxy management.

MobileProxy is a Go-based library designed to streamline the integration of proxy functionalities into mobile apps. It utilizes Go Mobile to generate mobile libraries, enabling you to configure your app's networking libraries to route traffic through a local proxy.

App without MobileProxy

Content app without MobileProxy

App with MobileProxy

Content app with MobileProxy

Step 1: Building MobileProxy mobile libraries

Use gomobile to compile the Go code into libraries for Android and iOS.

  1. Clone the Outline SDK repository:

    git clone https://github.com/OutlineFoundation/outline-sdk.git
    cd outline-sdk/x
  2. Build the Go Mobile binaries with go build:

    go build -o "$(pwd)/out/" golang.org/x/mobile/cmd/gomobile golang.org/x/mobile/cmd/gobind

    Adding Psiphon Support

    You can add support to use the Psiphon network by following these extra steps:

    • Contact the Psiphon team to obtain a config that gives you access to their network. This may require a contract.

    • Add the received Psiphon config to the fallback section of your SmartDialer config.

    • Build the Mobile Proxy using the -tags psiphon flag:

      go build -tags psiphon -o "$(pwd)/out/" golang.org/x/mobile/cmd/gomobile golang.org/x/mobile/cmd/gobind
    • Register Psiphon with the Smart dialer in your native code.

    The -tags psiphon flag is required because the Psiphon codebase is licensed under the GPL, which can impose license restrictions on your own code. You may want to consider obtaining a special license from them.

  3. Generate mobile libraries and add them to your project:

PATH="$(pwd)/out:$PATH" gomobile bind -ldflags='-s -w' -target=android -androidapi=21 -o "$(pwd)/out/mobileproxy.aar" github.com/OutlineFoundation/outline-sdk/x/mobileproxy

In Android Studio select File > Import Project… to import the generated out/mobileproxy.aar bundle. For more help see Go Mobile's Building and deploying to Android.

Step 2: Run the MobileProxy

  1. Initialize and start the MobileProxy local proxy within your app's runtime. You can use either a static transport configuration or the Smart Proxy for dynamic strategy selection.
  • Static transport configuration: Use the RunProxy function with a local address and transport configuration.
import mobileproxy.*

val dialer = StreamDialer("split:3")

// Use port zero to let the system pick an open port for you.
val proxy = Mobileproxy.runProxy("localhost:0", dialer)
// Configure your networking library using proxy.host() and proxy.port() or proxy.address().
// ...
// Stop running the proxy.
proxy.stop()
  • Smart Proxy: The Smart Proxy dynamically selects DNS and TLS strategies based on specified test domains. You need to specify the configuration strategy in YAML format (example).
val testDomains = Mobileproxy.newListFromLines("www.youtube.com\ni.ytimg.com")
val strategiesConfig = "..." // Config YAML.
val dialer = Mobileproxy.newSmartStreamDialer(testDomains, strategiesConfig, Mobileproxy.newStderrLogWriter())

// Use port zero to let the system pick an open port for you.
val proxy = Mobileproxy.runProxy("localhost:0", dialer)
// Configure your networking library using proxy.host() and proxy.port() or proxy.address().
// ...
// Stop running the proxy.
proxy.stop()
  1. Then, if you are using psiphon, register Psiphon with your Smart Dialer options in your native code.
import mobileproxy.Mobileproxy
import psiphon.Psiphon

// ...

val testDomains = Mobileproxy.newListFromLines("www.google.com\ni.ytimg.com")
// You can get a Psiphon config from the Psiphon team at [email protected].
val psiphonConfig = "<YOUR_PSIPHON_CONFIG_JSON_HERE>"
val config = """
dns:
- {system: {}}
tls:
- ""
fallback:
- {"psiphon": \(psiphonConfig)}
"""

val options = Mobileproxy.newSmartDialerOptions(testDomains, config)

// Register Psiphon
Psiphon.registerConfig(options, "psiphon")

try {
// Create the dialer
val dialer = options.newStreamDialer()
// ... use the dialer
} catch (e: Exception) {
// Handle error
}

Step 3: Configure HTTP clients and networking libraries

Configure your networking libraries to use the local proxy address and port.

Set the proxy with HttpClient.findProxy.

HttpClient client = HttpClient();
client.findProxy = (Uri uri) {
return "PROXY " + proxy.address();
};

Advanced: Generate a custom mobile library

For advanced use cases, you can generate your own mobile libraries:

  1. Create a Go library: Develop a Go package wrapping the required SDK functionalities.
  2. Generate mobile libraries: Use gomobile bind to produce Android Archives (AAR) and Apple Frameworks. Examples:
  3. Integrate into your app: Add the generated library to your mobile application.
note

Use gomobile bind on your custom package, not directly on the SDK packages.