From a55c0654fbb78a39c9a3672255e909317bacba07 Mon Sep 17 00:00:00 2001 From: olly Date: Wed, 30 Jun 2021 13:02:08 +0100 Subject: [PATCH] Improve Cronet and OkHttp READMEs PiperOrigin-RevId: 382279955 --- extensions/cronet/README.md | 103 ++++++++++++++++++++++++++---------- extensions/okhttp/README.md | 5 +- 2 files changed, 78 insertions(+), 30 deletions(-) diff --git a/extensions/cronet/README.md b/extensions/cronet/README.md index cc3c8b2137..2fc54a3f48 100644 --- a/extensions/cronet/README.md +++ b/extensions/cronet/README.md @@ -1,6 +1,15 @@ # ExoPlayer Cronet extension # -The Cronet extension is an [HttpDataSource][] implementation using [Cronet][]. +The Cronet extension is an [HttpDataSource][] implementation that uses +[Cronet][]. + +Cronet is the Chromium network stack made available to Android apps as a +library. It takes advantage of multiple technologies that reduce the latency and +increase the throughput of the network requests that your app needs to work, +including those made by ExoPlayer. It natively supports the HTTP, HTTP/2, and +HTTP/3 over QUIC protocols. Cronet is used by some of the world's biggest +streaming applications, including YouTube, and is our recommended network stack +for most use cases. [HttpDataSource]: https://exoplayer.dev/doc/reference/com/google/android/exoplayer2/upstream/HttpDataSource.html [Cronet]: https://developer.android.com/guide/topics/connectivity/cronet @@ -20,10 +29,6 @@ Alternatively, you can clone the ExoPlayer repository and depend on the module locally. Instructions for doing this can be found in ExoPlayer's [top level README][]. -By default, the extension will use the Cronet implementation in Google Play -Services. If you prefer, it's also possible to embed the Cronet implementation -directly into your application. See below for more details. - [top level README]: https://github.com/google/ExoPlayer/blob/release-v2/README.md ## Using the extension ## @@ -42,40 +47,80 @@ new DefaultDataSourceFactory( /* baseDataSourceFactory= */ new CronetDataSource.Factory(...) ); ``` -## Choosing between Google Play Services Cronet and Cronet Embedded ## +## Cronet implementations ## -The underlying Cronet implementation is available both via a [Google Play -Services](https://developers.google.com/android/guides/overview) API, and as a -library that can be embedded directly into your application. When you depend on -`com.google.android.exoplayer:extension-cronet:2.X.X`, the library will _not_ be -embedded into your application by default. The extension will attempt to use the -Cronet implementation in Google Play Services. The benefits of this approach -are: +To instantiate a `CronetDataSource.Factory` you'll need a `CronetEngine`. A +`CronetEngine` can be obtained from one of a number of Cronet implementations. +It's recommended that an application should only have a single `CronetEngine` +instance. -* A negligible increase in the size of your application. -* The Cronet implementation is updated automatically by Google Play Services. +### Available implementations ### -If Google Play Services is not available on a device, `CronetDataSourceFactory` -will fall back to creating `DefaultHttpDataSource` instances, or -`HttpDataSource` instances created by a `fallbackFactory` that you can specify. +#### Google Play Services #### -It's also possible to embed the Cronet implementation directly into your -application. To do this, add an additional gradle dependency to the Cronet -Embedded library: +By default, ExoPlayer's Cronet extension depends on +`com.google.android.gms:play-services-cronet`, which loads an implementation of +Cronet from Google Play Services. When Google Play Services is available, +this approach is beneficial because: -```gradle -implementation 'com.google.android.exoplayer:extension-cronet:2.X.X' -implementation 'org.chromium.net:cronet-embedded:XX.XXXX.XXX' -``` +* The increase in application size is negligible. +* The implementation is updated automatically by Google Play Services. -where `XX.XXXX.XXX` is the version of the library that you wish to use. The -extension will automatically detect and use the library. Embedding will add -approximately 8MB to your application, however it may be suitable if: +The disadvantage of this approach is that the implementation is not usable on +devices that do not have Google Play Services. Unless your application also +includes one of the alternative Cronet implementations described below, you will +not be able to instantiate a `CronetEngine` in this case. Your application code +should handle this by falling back to use `DefaultHttpDataSource` instead. -* Your application is likely to be used in markets where Google Play Services is +#### Cronet Embedded #### + +Cronet Embedded bundles a full Cronet implementation directly into your +application. To use it, add an additional dependency on +`org.chromium.net:cronet-embedded`. Cronet Embedded adds approximately 8MB to +your application, and so we do not recommend it for most use cases. That said, +use of Cronet Embedded may be appropriate if: + +* A large percentage of your users are in markets where Google Play Services is not widely available. * You want to control the exact version of the Cronet implementation being used. +#### Cronet Fallback #### + +There's also a fallback implementation of Cronet, which uses Android's default +network stack under the hood. It can be used by adding a dependency on +`org.chromium.net:cronet-fallback`. This implementation should _not_ be used +with ExoPlayer, since it's more efficient to use `DefaultHttpDataSource` +directly in this case. + +When using Cronet Fallback for other networking in your application, use the +more advanced approach to instantiating a `CronetEngine` described below so that +you know when your application's `CronetEngine` has been obtained from the +fallback implementation. In this case, avoid using it with ExoPlayer and use +`DefaultHttpDataSource` instead. + +### CronetEngine instantiation ### + +Cronet's [Send a simple request][] page documents the simplest way of building a +`CronetEngine`, which is suitable if your application is only using the +Google Play Services implementation of Cronet. + +For cases where your application also includes one of the other Cronet +implementations, you can use `CronetProvider.getAllProviders` to list the +available implementations. Providers can be identified by name: + +* `CronetProviderInstaller.PROVIDER_NAME`: Google Play Services implementation. +* `CronetProvider.PROVIDER_NAME_APP_PACKAGED`: Embedded implementation. +* `CronetProvider.PROVIDER_NAME_FALLBACK`: Fallback implementation . + +This makes it possible to iterate through the providers in your own order of +preference, trying to build a `CronetEngine` from each in turn using +`CronetProvider.createBuilder()` until one has been successfully created. This +approach also allows you to determine when the `CronetEngine` has been obtained +from Cronet Fallback, in which case you can avoid using it for ExoPlayer whilst +still using it for other networking performed by your application. + +[Send a simple request]: https://developer.android.com/guide/topics/connectivity/cronet/start + ## Links ## * [Javadoc][]: Classes matching `com.google.android.exoplayer2.ext.cronet.*` diff --git a/extensions/okhttp/README.md b/extensions/okhttp/README.md index 8a50346ced..2aad867e79 100644 --- a/extensions/okhttp/README.md +++ b/extensions/okhttp/README.md @@ -1,8 +1,11 @@ # ExoPlayer OkHttp extension # -The OkHttp extension is an [HttpDataSource][] implementation using Square's +The OkHttp extension is an [HttpDataSource][] implementation that uses Square's [OkHttp][]. +OkHttp is a modern network stack that's widely used by many popular Android +applications. It supports the HTTP and HTTP/2 protocols. + [HttpDataSource]: https://exoplayer.dev/doc/reference/com/google/android/exoplayer2/upstream/HttpDataSource.html [OkHttp]: https://square.github.io/okhttp/