TikTokLiveJava/collaboration.md

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/protoAfter usingMaven compilecommand on project, java classes are generated from those files. so then we can easily map incoming bytes to classes, for examplesWebcastGiftMessage 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

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.

 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

  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

 T onCustomEvent(EventConsumer<CustomEvent> event);

Finally we are good to go, out event has been included!