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```
42new DefaultDataSourceFactory(
43    ...
44    /* baseDataSourceFactory= */ new CronetDataSource.Factory(...) );
45```
46
47## Cronet implementations
48
49To instantiate a `CronetDataSource.Factory` you'll need a `CronetEngine`. A
50`CronetEngine` can be obtained from one of a number of Cronet implementations.
51It's recommended that an application should only have a single `CronetEngine`
52instance.
53
54### Available implementations
55
56#### Google Play Services
57
58By default, this module depends on
59`com.google.android.gms:play-services-cronet`, which loads an implementation of
60Cronet from Google Play Services. When Google Play Services is available, this
61approach is beneficial because:
62
63* The increase in application size is negligible.
64* The implementation is updated automatically by Google Play Services.
65
66The disadvantage of this approach is that the implementation is not usable on
67devices that do not have Google Play Services. Unless your application also
68includes one of the alternative Cronet implementations described below, you will
69not be able to instantiate a `CronetEngine` in this case. Your application code
70should handle this by falling back to use `DefaultHttpDataSource` instead.
71
72#### Cronet Embedded
73
74Cronet Embedded bundles a full Cronet implementation directly into your
75application. To use it, add an additional dependency on
76`org.chromium.net:cronet-embedded`. Cronet Embedded adds approximately 8MB to
77your application, and so we do not recommend it for most use cases. That said,
78use of Cronet Embedded may be appropriate if:
79
80* A large percentage of your users are in markets where Google Play Services is
81  not widely available.
82* You want to control the exact version of the Cronet implementation being used.
83
84#### Cronet Fallback
85
86There's also a fallback implementation of Cronet, which uses Android's default
87network stack under the hood. It can be used by adding a dependency on
88`org.chromium.net:cronet-fallback`. This implementation should *not* be used
89with `CronetDataSource`, since it's more efficient to use
90`DefaultHttpDataSource` directly in this case.
91
92When using Cronet Fallback for other networking in your application, use the
93more advanced approach to instantiating a `CronetEngine` described below so that
94you know when your application's `CronetEngine` has been obtained from the
95fallback implementation. In this case, avoid `CronetDataSource` and use
96`DefaultHttpDataSource` instead.
97
98### CronetEngine instantiation
99
100Cronet's [Send a simple request][] page documents the simplest way of building a
101`CronetEngine`, which is suitable if your application is only using the
102Google Play Services implementation of Cronet.
103
104For cases where your application also includes one of the other Cronet
105implementations, you can use `CronetProvider.getAllProviders` to list the
106available implementations. Providers can be identified by name:
107
108* `CronetProviderInstaller.PROVIDER_NAME`: Google Play Services implementation.
109* `CronetProvider.PROVIDER_NAME_APP_PACKAGED`: Embedded implementation.
110* `CronetProvider.PROVIDER_NAME_FALLBACK`: Fallback implementation.
111
112This makes it possible to iterate through the providers in your own order of
113preference, trying to build a `CronetEngine` from each in turn using
114`CronetProvider.createBuilder()` until one has been successfully created. This
115approach also allows you to determine when the `CronetEngine` has been obtained
116from Cronet Fallback, in which case you can avoid using `CronetDataSource`
117whilst still using Cronet Fallback for other networking performed by your
118application.
119
120[Send a simple request]: https://developer.android.com/guide/topics/connectivity/cronet/start
121
122## Links
123
124* [Javadoc][]
125
126[Javadoc]: https://exoplayer.dev/doc/reference/index.html
127