Add getting started section for the extractor
TODO: rename all docs to place getting started at the beginning.
This commit is contained in:
parent
b2a76985cd
commit
2e223b9ad9
|
@ -0,0 +1,89 @@
|
||||||
|
# Getting Started
|
||||||
|
This section provides you with the steps that are required to use the extractor.
|
||||||
|
|
||||||
|
### Implement a Downloader
|
||||||
|
|
||||||
|
The extractor needs to fetch websites and JSON files.
|
||||||
|
Its entire network activity is going through the downloader you pass to it.
|
||||||
|
We have predefined some methods which need to be implemented.
|
||||||
|
To get started, create a class extending
|
||||||
|
[`Downloader`](https://github.com/TeamNewPipe/NewPipeExtractor/blob/master/extractor/src/main/java/org/schabi/newpipe/extractor/downloader/Downloader.java).
|
||||||
|
We will call that class `DownloaderImpl` in this example.
|
||||||
|
|
||||||
|
``` Java
|
||||||
|
|
||||||
|
import org.schabi.newpipe.extractor.downloader.Downloader;
|
||||||
|
|
||||||
|
public class DownloaderImpl extends Downloader {
|
||||||
|
|
||||||
|
public DownloaderImpl() {
|
||||||
|
|
||||||
|
}
|
||||||
|
|
||||||
|
}
|
||||||
|
|
||||||
|
```
|
||||||
|
Your IDE will prompt you to implement at least one method:
|
||||||
|
|
||||||
|
``` Java
|
||||||
|
/**
|
||||||
|
* Do a request using the specified {@link Request} object.
|
||||||
|
*
|
||||||
|
* @return the result of the request
|
||||||
|
*/
|
||||||
|
public Response execute(@Nonnull Request request) throws IOException, ReCaptchaException {
|
||||||
|
// your code goes here
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
You can find two example implementations of the Downloader below.
|
||||||
|
Both use an old OkHttp version (version 3) to support Android 4. However, you do not need to use OkHttp.
|
||||||
|
In case you want to use it and do not need to support old Android versions,
|
||||||
|
we recommend using a newer OkHttp version, because the version used in the example will only receive security updates until December 2021.
|
||||||
|
|
||||||
|
- [Downloader implementation for NewPipe Extractor tests](https://github.com/TeamNewPipe/NewPipeExtractor/blob/master/extractor/src/test/java/org/schabi/newpipe/downloader/DownloaderTestImpl.java)
|
||||||
|
- [Downloader implementation of the NewPipe app](https://github.com/TeamNewPipe/NewPipe/blob/master/app/src/main/java/org/schabi/newpipe/DownloaderImpl.java)
|
||||||
|
Note: This implementation contains some additional methods which are not necessary for general use cases.
|
||||||
|
|
||||||
|
|
||||||
|
Depending on your use case and your downloader implementation, we suggest you to make use of the singleton pattern.
|
||||||
|
|
||||||
|
#### Browser Agent
|
||||||
|
|
||||||
|
When making requests to websites, you should define a user agent for the request headers. We have build our tests on
|
||||||
|
```
|
||||||
|
Mozilla/5.0 (Windows NT 10.0; rv:78.0) Gecko/20100101 Firefox/78.0
|
||||||
|
```
|
||||||
|
For this reason, we strongly recommend using that agent or any other that is used in the [testimplementation in NewPipe Extractor](https://github.com/TeamNewPipe/NewPipeExtractor/blob/master/extractor/src/test/java/org/schabi/newpipe/downloader/DownloaderTestImpl.java).
|
||||||
|
However, a service might want to override the default user agent.
|
||||||
|
This is sometimes necessary to get special versions of a website (e.g. mobile or legacy version).
|
||||||
|
Please respect that when implementing the `execute(@Nonnull Request request)` method.
|
||||||
|
|
||||||
|
## Initialize NewPipe
|
||||||
|
|
||||||
|
``` Java
|
||||||
|
NewPipe.init(
|
||||||
|
/*
|
||||||
|
New instance of your downloader implementation.
|
||||||
|
If you implemented the singleton pattern, use DownlaoderImpl.getInstance() instead.
|
||||||
|
*/
|
||||||
|
new DownloaderImpl()
|
||||||
|
);
|
||||||
|
```
|
||||||
|
You can also set a default localization
|
||||||
|
``` Java
|
||||||
|
NewPipe.init(
|
||||||
|
new DownloaderImpl(),
|
||||||
|
new Localization("EN", "US")
|
||||||
|
);
|
||||||
|
```
|
||||||
|
and a default content country. However, not all services support those, yet.
|
||||||
|
``` Java
|
||||||
|
NewPipe.init(
|
||||||
|
new DownloaderImpl(),
|
||||||
|
new Localization("EN", "US"),
|
||||||
|
new ContentCountry("EN-US")
|
||||||
|
);
|
||||||
|
```
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue