Aggiungi Outline SDK alla tua app mobile

Questo documento illustra come integrare Outline SDK nelle tue applicazioni mobile ed è incentrato sulla libreria MobileProxy per una gestione semplificata del proxy locale.

MobileProxy è una libreria basata su Go, progettata per semplificare l'integrazione delle funzionalità proxy nelle app mobile. Utilizza Go Mobile per generare librerie per dispositivi mobili, consentendoti di configurare le librerie di networking della tua app in modo da instradare il traffico attraverso un proxy locale.

App senza MobileProxy

App con MobileProxy

Passaggio 1: crea librerie per dispositivi mobili MobileProxy

Usa gomobile per compilare il codice Go in librerie per Android e iOS.

1. Clona il repository Outline SDK:

   git clone https://github.com/Jigsaw-Code/outline-sdk.git
   cd outline-sdk/x
   

2. Crea i file binari Go Mobile con go build:

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

   Aggiunta del supporto di Psiphon

   Puoi aggiungere il supporto per l'utilizzo della rete Psiphon eseguendo questi passaggi aggiuntivi:

   • Contatta il team di Psiphon per ottenere una configurazione di accesso alla loro rete. Può essere necessario stipulare un contratto.
   • Aggiungi la configurazione di Psiphon alla sezione fallback della configurazione del tuo SmartDialer.

   • Crea il MobileProxy usando il flag -tags psiphon:

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

   Il flag -tags psiphon è necessario perché l'utilizzo del codebase di Psiphon è concesso ai sensi della licenza GPL, che può imporre limitazioni sul tuo codice. Valuta l'opportunità di richiedere una licenza speciale.

3. Genera le librerie per dispositivi mobili e aggiungile al progetto:

   Android

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

   In Android Studio seleziona File > Import Project… per importare il pacchetto out/mobileproxy.aar generato. Per altre informazioni, vedi le istruzioni sulla creazione e distribuzione in Android di Go Mobile.

   iOS

   PATH="$(pwd)/out:$PATH" gomobile bind -ldflags='-s -w' -target=ios -iosversion=11.0 -o "out/mobileproxy.xcframework" github.com/Jigsaw-Code/outline-sdk/x/mobileproxy
   

   Trascina il pacchetto out/mobileproxy.xcframework nel progetto Xcode. Per altre informazioni, vedi le istruzioni sulla creazione e distribuzione in iOS di Go Mobile.

Passaggio 2: esegui il MobileProxy

Inizializza e avvia il proxy locale MobileProxy con il runtime della tua app. Puoi usare una configurazione del trasporto statica o lo Smart Proxy per la selezione dinamica della strategia.

• Configurazione del trasporto statica: usa la funzione RunProxy con una configurazione del trasporto e un indirizzo locali.

  Android

  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()
  

  iOS

  import Mobileproxy
  
  let dialer = MobileproxyStreamDialer("split:3")
  
  // Use port zero to let the system pick an open port for you.
  let proxy = MobileproxyRunProxy("localhost:0", dialer)
  // Configure your networking library using proxy.host() and proxy.port() or proxy.address().
  // ...
  // Stop running the proxy.
  proxy.stop()
  

• Smart Proxy: lo Smart Proxy seleziona in modo dinamico le strategie DNS e TLS in base ai domini di test specificati. Devi specificare la strategia di configurazione in formato YAML (esempio).

  Android

  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()
  

  iOS

  import Mobileproxy
  
  var dialerError: NSError?
  let testDomains = MobileproxyNewListFromLines("www.youtube.com\ni.ytimg.com")
  let strategiesConfig = "..."  // Config YAML.
  let dialer = MobileproxyNewSmartStreamDialer(
      testDomains,
      strategiesConfig,
      MobileproxyNewStderrLogWriter(),
      &dialerError
  )
  
  var proxyError: NSError?
  // Use port zero to let the system pick an open port for you.
  MobileproxyRunProxy("localhost:0", dialer, &proxyError)
  // Configure your networking library using proxy.host() and proxy.port() or proxy.address().
  // ...
  // Stop running the proxy.
  proxy.stop()
  

Passaggio 3: configura i client HTTP e le librerie di networking

Configura le tue librerie di networking in modo da usare la porta e l'indirizzo del proxy locali.

HttpClient Dart/Flutter

Imposta il proxy con HttpClient.findProxy.

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

OkHttp (Android)

Imposta il proxy con OkHttpClient.Builder.proxy.

val proxyConfig = Proxy(Proxy.Type.HTTP, InetSocketAddress(proxy.host(), proxy.port()))
val client = OkHttpClient.Builder().proxy(proxyConfig).build()

JVM (Java, Kotlin)

Configura il proxy da usare con le proprietà di sistema:

System.setProperty("http.proxyHost", proxy.host())
System.setProperty("http.proxyPort", String.valueOf(proxy.port()))
System.setProperty("https.proxyHost", proxy.host())
System.setProperty("https.proxyPort", String.valueOf(proxy.port()))

WebView Android

Applica una configurazione proxy a tutti gli oggetti WebView della tua applicazione con la libreria androidx.webview:

ProxyController.getInstance()
    .setProxyOverride(
        ProxyConfig.Builder()
            .addProxyRule(this.proxy!!.address())
            .build(),
        {}, // execution context for the following callback - do anything needed here once the proxy is applied, like refreshing web views
        {} // callback to be called once the ProxyConfig is applied
    )

WebView iOS

A partire da iOS 17 è possibile aggiungere una configurazione proxy a un oggetto WKWebView usando la sua proprietà WKWebsiteDataStore:

let configuration = WKWebViewConfiguration()
let endpoint = NWEndpoint.hostPort(host: NWEndpoint.Host(proxyHost), port: NWEndpoint.Port(proxyPort)!)
let proxyConfig = ProxyConfiguration.init(httpCONNECTProxy: endpoint)
let websiteDataStore = WKWebsiteDataStore.default()
websiteDataStore.proxyConfigurations = [proxyConfig]
let webview = WKWebView(configuration: configuration)

Uso avanzato: genera una libreria per dispositivi mobili avanzata

Per i casi d'uso avanzati puoi generare librerie per dispositivi mobili personalizzate:

1. Crea una libreria Go: sviluppa un pacchetto Go con le funzionalità dell'SDK necessarie.
2. Genera librerie per dispositivi mobili: usa gomobile bind per produrre file Android Archive (AAR) e framework Apple. Esempi:
   • Archivio Android di Outline
   • Framework Apple di Outline
3. Integra la libreria nell'app: aggiungi la libreria generata alla tua applicazione mobile.

Nota: usa gomobile bind sul tuo pacchetto personalizzato, non direttamente sui pacchetti dell'SDK.