1# Cronet DataSource module
2
3This module provides an [HttpDataSource][] implementation that uses [Cronet][].
4
5Cronet is the Chromium network stack made available to Android apps as a
6library. It takes advantage of multiple technologies that reduce the latency and
7increase the throughput of the network requests that your app needs to work. It
8natively supports the HTTP, HTTP/2, and HTTP/3 over QUIC protocols. Cronet is
9used by some of the world's biggest streaming applications, including YouTube,
10and is our recommended network stack for most use cases.
11
12[HttpDataSource]: https://exoplayer.dev/doc/reference/com/google/android/exoplayer2/upstream/HttpDataSource.html
13[Cronet]: https://developer.android.com/guide/topics/connectivity/cronet
14
15## Getting the module
16
17The easiest way to get the module is to add it as a gradle dependency:
18
19```gradle
20implementation 'com.google.android.exoplayer:extension-cronet:2.X.X'
21```
22
23where `2.X.X` is the version, which must match the version of the other media
24modules being used.
25
26Alternatively, you can clone this GitHub project and depend on the module
27locally. Instructions for doing this can be found in the [top level README][].
28
29[top level README]: https://github.com/google/ExoPlayer/blob/release-v2/README.md
30
31## Using the module
32
33Media components request data through `DataSource` instances. These instances
34are obtained from instances of `DataSource.Factory`, which are instantiated and
35injected from application code.
36
37If your application only needs to play http(s) content, using the Cronet
38extension is as simple as updating `DataSource.Factory` instantiations in your
39application code to use `CronetDataSource.Factory`. If your application also
40needs to play non-http(s) content such as local files, use:
41
42```
43new DefaultDataSource.Factory(
44    ...
45    /* baseDataSourceFactory= */ new CronetDataSource.Factory(...) );
46```
47
48## Cronet implementations
49
50To instantiate a `CronetDataSource.Factory` you'll need a `CronetEngine`. A
51`CronetEngine` can be obtained from one of a number of Cronet implementations.
52It's recommended that an application should only have a single `CronetEngine`
53instance.
54
55### Available implementations
56
57#### Google Play Services
58
59By default, this module depends on
60`com.google.android.gms:play-services-cronet`, which loads an implementation of
61Cronet from Google Play Services. When Google Play Services is available, this
62approach is beneficial because:
63
64* The increase in application size is negligible.
65* The implementation is updated automatically by Google Play Services.
66
67The disadvantage of this approach is that the implementation is not usable on
68devices that do not have Google Play Services. Unless your application also
69includes one of the alternative Cronet implementations described below, you will
70not be able to instantiate a `CronetEngine` in this case. Your application code
71should handle this by falling back to use `DefaultHttpDataSource` instead.
72
73#### Cronet Embedded
74
75Cronet Embedded bundles a full Cronet implementation directly into your
76application. To use it, add an additional dependency on
77`org.chromium.net:cronet-embedded`. Cronet Embedded adds approximately 8MB to
78your application, and so we do not recommend it for most use cases. That said,
79use of Cronet Embedded may be appropriate if:
80
81* A large percentage of your users are in markets where Google Play Services is
82  not widely available.
83* You want to control the exact version of the Cronet implementation being used.
84
85#### Cronet Fallback
86
87There's also a fallback implementation of Cronet, which uses Android's default
88network stack under the hood. It can be used by adding a dependency on
89`org.chromium.net:cronet-fallback`. This implementation should *not* be used
90with `CronetDataSource`, since it's more efficient to use
91`DefaultHttpDataSource` directly in this case.
92
93When using Cronet Fallback for other networking in your application, use the
94more advanced approach to instantiating a `CronetEngine` described below so that
95you know when your application's `CronetEngine` has been obtained from the
96fallback implementation. In this case, avoid `CronetDataSource` and use
97`DefaultHttpDataSource` instead.
98
99### CronetEngine instantiation
100
101Cronet's [Send a simple request][] page documents the simplest way of building a
102`CronetEngine`, which is suitable if your application is only using the
103Google Play Services implementation of Cronet.
104
105For cases where your application also includes one of the other Cronet
106implementations, you can use `CronetProvider.getAllProviders` to list the
107available implementations. Providers can be identified by name:
108
109* `CronetProviderInstaller.PROVIDER_NAME`: Google Play Services implementation.
110* `CronetProvider.PROVIDER_NAME_APP_PACKAGED`: Embedded implementation.
111* `CronetProvider.PROVIDER_NAME_FALLBACK`: Fallback implementation.
112
113This makes it possible to iterate through the providers in your own order of
114preference, trying to build a `CronetEngine` from each in turn using
115`CronetProvider.createBuilder()` until one has been successfully created. This
116approach also allows you to determine when the `CronetEngine` has been obtained
117from Cronet Fallback, in which case you can avoid using `CronetDataSource`
118whilst still using Cronet Fallback for other networking performed by your
119application.
120
121[Send a simple request]: https://developer.android.com/guide/topics/connectivity/cronet/start
122
123## Links
124
125* [Javadoc][]
126
127[Javadoc]: https://exoplayer.dev/doc/reference/index.html
128