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 with co-hosting.
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 configuring the bottomMenuBarConfig and listening to the corresponding event.
let liveVC = ZegoUIKitPrebuiltLiveStreamingVC(yourAppID, appSign: yourAppSign, userID: yourUserID, userName: yourUserName, liveID: yourLiveID, config: config)
// Add gift button.
let giftButton = UIButton(type: .system)
giftButton.backgroundColor = .red
giftButton.setTitle("Gift", for: .normal)
giftButton.setTitleColor(.white, for: .normal)
giftButton.addTarget(self, action: #selector(sendGift), for: .touchUpInside)
liveVC.addButtonToBottomMenuBar(giftButton, role: .audience)
liveVC.addButtonToBottomMenuBar(giftButton, role: .coHost)
liveVC.modalPresentationStyle = .fullScreen
self.present(liveVC, animated: true, completion: nil)
// Add event handler.
ZegoUIKit.shared.addEventHandler(self)
Implement the gift-sending logic
When the viewers click the gift sending button, it triggers the corresponding API of your business server. The request parameters can be like this:
{
"room_id": "room888", // The livestream 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
"access_token": "fasd2r34dfasd...fasdf", // The Token used for authentication
"timestamp": 1670814533, // Request timestamp
}
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.
The viewer receives a corresponding status code after processing. A message queue is then created to notify the host and other viewers about the gift.
The demo employs Next.js to showcase how ZEGOCLOUD Server API is called. You may download the source code for reference.
Notify the host and viewers to display gift animation
To display gift animations to the host and viewers, send a notification using the send in-room messages API with MessageType: 2.
We recommend combining multiple gifts into a single message to avoid exceeding the rate limit of 10 requests per second per app ID. For example:
While this signaling ensures delivery under normal network conditions, it may be lost in rare cases, such as when the gift receiver experiences network issues and fails to receive the signal.
{
"FromUserId": "serverID",
"RoomId": "room888",
"MessageType": 2,
"Priority": 1,
"MessageBody": {
"Message": [
{
"user_id": "user987",
"user_name": "James",
"gift_type": 1001,
"gift_cout": 2,
"timestamp": 1670814533,
},
...
],
"ExtendedData":"",
}
}
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.
@objc func sendGift() {
let parameters: [String: Any] = [
"app_id": appID,
"server_secret": serverSecret,
"room_id": liveIDTextField.text!,
"user_id": userID,
"user_name": userName!,
"gift_type": 1001,
"gift_count": 1,
"timestamp": "123"
]
let session = URLSession(configuration: .default)
let url = URL(string: "https://zego-virtual-gift.vercel.app/api/send_gift")
var request = URLRequest(url: url!)
request.httpMethod = "POST"
request.addValue("application/json", forHTTPHeaderField: "Content-Type")
do {
let jsonData = try JSONSerialization.data(withJSONObject: parameters, options: [])
request.httpBody = jsonData
} catch {
}
print("Start sending gift...")
let task = session.dataTask(with: request) { data, response, error in
if let httpResponse = response as? HTTPURLResponse,
httpResponse.statusCode == 200 {
print("Send Gift success.")
//show gift animation
DispatchQueue.main.async {
self.giftView.show("vap.mp4", container: self.liveVC.view)
}
} else {
print("Send Gift fail.")
}
}
task.resume()
}
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.
// Add event handler
ZegoUIKit.shared.addEventHandler(self)
extension ViewController: ZegoUIKitEventHandle {
func onInRoomCommandMessageReceived(_ messages: [ZegoSignalingInRoomCommandMessage], roomID: String) {
if let message = messages.first {
if message.senderUserID != userID {
//show gift animation
DispatchQueue.main.async {
self.giftView.show("vap.mp4", container: self.liveVC.view)
}
}
}
}
}
Run a demo
To access the sample code for this feature, download it from here.