mirror of
https://github.com/jwdeveloper/TikTokLiveJava.git
synced 2026-02-27 16:59:39 -05:00
212 lines
7.8 KiB
Markdown
212 lines
7.8 KiB
Markdown
# Collaboration Guide
|
|
|
|
Are you willing to help or improve TikTokLiveJava?
|
|
|
|
|
|
|
|
|
|
### Project setup
|
|
|
|
1. Clone project to your favorite IDE (IntelliJ recommended) https://github.com/jwdeveloper/TikTokLiveJava.git
|
|
|
|
2. After project is cloned you can encounter error that some classes are missing
|
|
Don't worry this is normal! To fix that use `Maven compile` command for the
|
|
root project
|
|
|
|
|
|
|
|
### How does library works?
|
|
|
|
We can divide working of library to 4 important parts
|
|
|
|
- Getting info about live from TikTok. Library is making 3 https requests
|
|
- first for getting live `Room_ID`
|
|
- second for getting more specific live metadata such as live title, host name...
|
|
- third to `Sign API` that returns access token that is later use for connecting
|
|
to TikTok websocket
|
|
- Connecting to TikTok websocket (PushServer)
|
|
|
|
After successful connection to TikTok, `pushServer` starts to send `ProtocolBuffer`
|
|
messages in binary format. This is very important to understand `ProtocolBuffer. Don't worry it is not complicated :).
|
|
All the proto files are included under `API/src/main/proto` After using `Maven compile` command on project, java classes are generated from
|
|
those files. so then we can easily map incoming bytes to classes, for examples
|
|
`WebcastGiftMessage message = WebcastGiftMessage.parseFrom(incomingBytesArray)`
|
|
|
|
- Mapping TikTok data to events
|
|
|
|
At this point we have TikTok data inside protocol-buffer classes now we want
|
|
to map it to events. Why? because `protocol-buffer classes` might be changed at any point,
|
|
but we want to keep library code structure consistent across versions.
|
|
so for example `WebcastGiftMessage` is mapped to `TikTokGiftEvent`
|
|
|
|
- trigger events
|
|
|
|
When the events objects are done last step is to trigger them. And that's it!
|
|
`tikTokEventObserver.publish(liveClient, tiktokGiftEvent)`
|
|
|
|
|
|
|
|
### Project structure
|
|
Project is made from few modules the most important one are
|
|
|
|
#### API
|
|
|
|
Contains interfaces and data classes. All code included in this
|
|
project is ment to be visible to people that are using library.
|
|
|
|
|
|
- All the events can be found user `io.github.jwdeveloper.tiktok.data.events`
|
|
- All the class data that are used in events is under `io.github.jwdeveloper.tiktok.data.models`
|
|
- All the protocol-buffer classes will be generated at namespack `io.github.jwdeveloper.tiktok.messages` they are at location `API\target\classes\io\github\jwdeveloper\tiktok\messages`
|
|
|
|
#### Client
|
|
|
|
Contains implementation of `API` modules interfaces and all the code
|
|
important classes
|
|
|
|
- `TikTokLiveClient` core class that is use to mangae connection disconnection
|
|
- `TikTokLiveClientBuilder` preparing and creating `TikTokLiveClient` class
|
|
- `TikTokApiService` use for Http requests to TikTok/Sign API
|
|
- `TikTokWebSocketClient` receiving all ProtocolBuffer messages from TikTok
|
|
- `TikTokMessageHandler` **heart of library** it finds suitable mapper for incoming data and triggers its mapping handler as result list of events
|
|
is created and published. **check out** `TikTokMessageHandler.handleSingleMessage`
|
|
- `TikTokMessageHandlerRegistration` register all mappings `protol-buffer` classes -> `events`
|
|
- `TikTokEventObserver` used to register and trigger TikTok events
|
|
|
|
|
|
### There are also few more modules made purely for testing and debbuging code
|
|
|
|
#### Examples
|
|
Project is made to show up new features and present basic
|
|
example of library. While developing you can use it this project as playground
|
|
|
|
#### Tools
|
|
Project that contains code generators.
|
|
The most useful one is class `GenerateGiftsEnum` that download gifts json from TikTok
|
|
and generates code for `Gift` enum that is later added to `API` module at path `io.github.jwdeveloper.tiktok.data.models.gifts.Gift`
|
|
|
|
#### Tools-EventsCollector
|
|
Tool that can be used to store all `protocol-buffer` and `events` from live to `sqlLite` database or `Json` file
|
|
It is very handy for later debuging `protocol-buffer` and `events` data
|
|
|
|
#### Tools-EventsWebViewer
|
|
Tools that runs website that collects and display pure data from TikTok
|
|
very useful for debuging
|
|
|
|
#### Tools-ReadmeGenerator
|
|
Generates readme file from template
|
|
|
|
|
|
|
|
|
|
### How to add new Event?
|
|
|
|
First step is to create class that represends event. Remember, all the events classes must be located in the `io.github.jwdeveloper.tiktok.data.events` package
|
|
|
|
```java
|
|
package io.github.jwdeveloper.tiktok.data.events;
|
|
|
|
import io.github.jwdeveloper.tiktok.annotations.EventMeta;
|
|
import io.github.jwdeveloper.tiktok.annotations.EventType;
|
|
import io.github.jwdeveloper.tiktok.data.events.common.TikTokHeaderEvent;
|
|
import io.github.jwdeveloper.tiktok.messages.data.User;
|
|
import lombok.Data;
|
|
|
|
|
|
@Data //lombok annotation
|
|
@EventMeta(eventType = EventType.Message) //this annotation is used by readme generater code
|
|
public class CustomEvent extends TikTokHeaderEvent
|
|
{
|
|
private final User user;
|
|
private final String title;
|
|
|
|
public CustomEvent(User user,String title)
|
|
{
|
|
this.user = user;
|
|
this.title = title;
|
|
}
|
|
}
|
|
```
|
|
Now we can jump to the `io.github.jwdeveloper.tiktok.handlers.TikTokMessageHandlerRegistration` class. It is used
|
|
to define mappings from incoming protocolbuffer data to Events.
|
|
Note that all classes that starts with `Webcast` represents protocolbuffer data that is coming from tiktok
|
|
Note all `Webcast` classes are generated from `proto` file that is defined in `API/src/main/proto/webcast.proto` I recommand to use `protocolbuffer` plugin for inteliji
|
|
|
|
|
|
For this example we registered new mapping that is triggered every time `WebcastGiftMessage` is comming
|
|
from TikTok.
|
|
|
|
```java
|
|
public void init() {
|
|
|
|
registerMapping(WebcastGiftMessage.class, bytes ->
|
|
{
|
|
try {
|
|
WebcastGiftMessage tiktokData = WebcastGiftMessage.parseFrom(bytes);
|
|
|
|
io.github.jwdeveloper.tiktok.messages.data.User tiktokProtocolBufferUser = tiktokData.getUser();
|
|
io.github.jwdeveloper.tiktok.data.models.users.User tiktokLiveJavaUser = User.map(tiktokProtocolBufferUser);
|
|
|
|
return new CustomEvent(tiktokLiveJavaUser, "hello word");
|
|
} catch (Exception e) {
|
|
throw new TikTokLiveException("Unable to parse our custom event", e);
|
|
}
|
|
});
|
|
|
|
//ConnectionEvents events
|
|
registerMapping(WebcastControlMessage.class, this::handleWebcastControlMessage);
|
|
|
|
//Room status events
|
|
registerMapping(WebcastLiveIntroMessage.class, roomInfoHandler::handleIntro);
|
|
registerMapping(WebcastRoomUserSeqMessage.class, roomInfoHandler::handleUserRanking);
|
|
|
|
registerMapping(WebcastCaptionMessage.class, TikTokCaptionEvent.class);
|
|
//... more mappings down there
|
|
}
|
|
```
|
|
|
|
|
|
|
|
|
|
Next step is to open `TikTokLiveClientBuilder` and add method for handling our new event
|
|
|
|
``` java
|
|
|
|
public LiveClientBuilder onCustomEvent(EventConsumer<CustomEvent> event) {
|
|
tikTokEventHandler.subscribe(CustomEvent.class, event);
|
|
return this;
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
To make `onCustomEvent` method visible from `TikTokLive.newClient("asds").onCustomEvent()` we
|
|
need to also include it to interface `EventsBuilder`
|
|
|
|
``` java
|
|
T onCustomEvent(EventConsumer<CustomEvent> event);
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Finally we are good to go, out event has been included!
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|