Send virtual gifts

The virtual gifting function is a novel feature found in social apps that allows users to send virtual gifts to a host. These gifts can take the form of a variety of items, ranging from a cup of coffee to a car.

The aim of this function is to enhance interactivity and liveliness within social apps. By sending virtual gifts, viewers can connect with the host during live shows.

This document will explain how to implement virtual gifting.

Prerequisites

Before you begin, make sure you complete the integration by referring to the Quick start.

Implementation

Create a virtual-gifting entrance

Create an entrance for sending virtual gifts, which is a button that can be clicked to send virtual gifts. To do so, add a button by addButtonToBottomMenuBar and add corresponding event.

Untitled


ZegoUIKitPrebuiltLiveAudioRoomFragment fragment = ZegoUIKitPrebuiltLiveAudioRoomFragment.newInstance(appID,appSign, userID, userName, roomID, config);

ImageView imageView = new ImageView(context);
imageView.setImageResource(R.drawable.presents_icon);
int size = Utils.dp2px(36f, context.getResources().getDisplayMetrics());
int marginTop = Utils.dp2px(10f, context.getResources().getDisplayMetrics());
int marginBottom = Utils.dp2px(16f, context.getResources().getDisplayMetrics());
int marginEnd = Utils.dp2px(8, context.getResources().getDisplayMetrics());
LayoutParams layoutParams = new LayoutParams(size, size);
layoutParams.topMargin = marginTop;
layoutParams.bottomMargin = marginBottom;
layoutParams.rightMargin = marginEnd;
imageView.setLayoutParams(layoutParams);

fragment.addButtonToBottomMenuBar(Collections.singletonList(giftButton), ZegoLiveAudioRoomRole.AUDIENCE);

getSupportFragmentManager().beginTransaction().replace(R.id.fragment_container, fragment).commitNow();

Copied!

Implement the gift-sending logic

When the viewers click the gift sending button, you can sends String data to room users by ZegoUIKit.getSignalingPlugin().sendInRoomCommandMessage: the content can be like this:

Untitled

{
  "room_id": "room888",   // The live audio room ID
  "user_id": "user987",   // The user ID of the gift sender
  "user_name": "James",   // The user name of the gift sender
  "gift_type": 1001,      // Gift type
  "gift_count": 2,         // Number of gifts
  "timestamp": 1670814533,    // Request timestamp
}

Copied!

You have the flexibility to modify request parameters based on your business requirements. Once a viewer requests to send a gift, your server will perform the following actions:

Verify if the user's account balance meets the required amount based on the parameters.
Deduct the fees from the user's account balance.
Increase the gift amount for the host.

Complete code is like this:

Untitled

imageView.setOnClickListener(v -> {
    JSONObject jsonObject = new JSONObject();
    try {
        jsonObject.put("room_id", roomID);
        jsonObject.put("user_id", userID);
        jsonObject.put("user_name", userName);
        jsonObject.put("gift_type", 1001);
        jsonObject.put("gift_count", 1);
        jsonObject.put("timestamp", System.currentTimeMillis());
    } catch (JSONException e) {
        e.printStackTrace();
    }
    ZegoUIKit.getSignalingPlugin().sendInRoomCommandMessage(jsonObject.toString(), roomID,
        new SendRoomMessageCallback() {
            @Override
            public void onResult(int errorCode, String errorMessage) {
                // showAnimation();
            }
        });
});

Copied!

Listen to gift messages and display gift animation

To display the gift animation, simply monitor the gift message on the client. Once a new gift message arrives, play the animation. Different roles require different gift message callbacks.

For cool animation effects, use animation libraries such as Lottie or SVGA to display the file on the screen.

Gift sender

After sending a gift, the gift sender can confirm its successful delivery by checking the status code of the gift-sending API. If the API returns a success code, the gift animation will display.

Untitled

ZegoUIKit.getSignalingPlugin().sendInRoomCommandMessage(jsonObject.toString(), roomID,
    new SendRoomMessageCallback() {
        @Override
        public void onResult(int errorCode, String errorMessage) {
            showAnimation();
        }
    });

Copied!

Host and rest of the viewers

Suppose the server uses an unreliable signaling channel to broadcast messages. In that case, it needs to monitor the notification callback method onInRoomCommandReceived of unreliable messages to determine whether someone has sent a gift. When a new gift notification is received, it displays the gift effect.

If the server uses an unreliable signaling channel to broadcast messages, it can monitor the onInRoomCommandReceived notification callback method for unreliable messages. This allows it to detect when a gift has been sent. Upon receiving a new gift notification, the gift effect will display.

Untitled

// when someone send gift in room, will receive InRoomCommandMessage
ZegoUIKit.getSignalingPlugin().addInRoomCommandMessageListener(new ZegoUIKitSignalingPluginInRoomCommandMessageListener() {
    @Override
    public void onInRoomCommandMessageReceived(List<ZegoSignalingInRoomCommandMessage> messages,
        String roomID) {
        for (ZegoSignalingInRoomCommandMessage message : messages) {
            if (!message.senderUserID.equals(userID) && message.text.contains("gift_type")) {
                showAnimation();
            }
        }

    }
});

Copied!

Run a demo

To access the sample code for this feature, download it from here.