Push Notification Overview

Push notifications allow you to deliver messages to users instantly and stay in touch with them, helping to increase user retention and improve the user experience. TapTap Developer Services provides a unified service that allows you to send push notifications to both Android and iOS users.

In addition to sending push notifications using the iOS and Android SDK, you can also trigger them using the REST API.

Before you can use the Push Notification service, please make sure you have enabled the service on Developer Center > Your game > Game Services > Configuration. You may need to wait up to 3 minutes after clicking on the button before using the service.

Glossary

Installation

An Installation is a unique identifier for a device that accepts push notifications from your application. Each Installation corresponds to an entry in the _Installation table. An Installation is essentially an LCObject that contains the following properties:

Name	Applicable platform	Description
badge	iOS	The badge at the top of the app icon that shows the number of new notifications.
channels		The channel to which the device is subscribed. It can contain only uppercase and lowercase letters, numbers, underscores (_), hyphens (-), equal signs (=), and Chinese characters.
deviceProfile		deviceProfile is used to specify the name of the certificate or configuration used by the current device if there are multiple iOS certificates or Android mixpush configurations. Its value must match the certificate name or configuration name set up on Developer Center > Your game > Game Services > Cloud Services > Push Notification > Settings, or push notifications won’t be delivered successfully. The value of deviceProfile must start with a letter and can only contain uppercase and lowercase letters, numbers, and underscores. You can also leave this field empty. deviceProfile is a special field that only supports equals queries.
deviceToken	iOS	A unique identifier used by APNs.
apnsTopic	iOS	This field must be configured if you are using push notification based on Token Authentication. The iOS SDK automatically uses the application’s bundle ID as apnsTopic, but you will need to set this field manually in the following situations: 1. The version of the iOS SDK you are using is below v4.2.0; 2. You are not using the iOS SDK (for example, you are using React Native); 3. You are using a different topic than the bundle ID.
deviceType		The type of the device. Can be ios or android.
installationId	Android	A unique identifier generated by the SDK for each Android device.
timeZone		A string representing the timezone of the device.

Notification

Each Notification corresponds to a record displayed on Developer Center > Your game > Game Services > Cloud Services > Push Notification > Push records, which corresponds to a push notification being sent. It contains the following properties:

Name	Applicable platform	Description
notificationId		The ID of the push notification.
msg		A JSON object that contains the contents of the push notification. See 消息内容参数 for more information.
invalidTokens	iOS	The number of INVALID TOKEN errors returned by APNs. If this number seems high, please check the validity of the certificate.
prod	iOS	The environment of the certificate being used. dev means the development environment and prod means the production environment.
status		The status of the push notification. in-queue means the push notification is in the queue. done means the push notification has been delivered. scheduled means the push notification is scheduled and is waiting to be triggered.
devices		The number of target devices for this push notification, which is the number of valid devices queried from the _Installation table when this push notification request is being processed. This may not be the same as the number of devices that actually received the push notification. A device is “valid” if its valid property in the _Installation table is true and its updatedAt is within 3 months. Target devices may include inactive devices on which your application has been uninstalled. These devices may not be able to receive the push notification.
successes		The number of devices to which the push notification was successfully sent. For push notifications sent directly to Android devices, this means that the devices received the push notification. For push notifications sent to iOS devices or sent to Android devices via mixpush, this means that the push notification was sent to APNs or the corresponding mixpush platforms. The number of devices to which the push notification was successfully sent through a particular channel can be found in the [lc/ios/fcm/hms/mi/oppo/vivo/meizu]Successes field.
where		The conditions used to query the _Installation table. Devices that match the conditions will receive the push notification.
errors		If an error occurred with the push notification, this is the error message.
from-service		push means the push notification is triggered directly; rtm means the push notification is triggered by a message sent through the Instant Messaging service.
push-time		If this is a scheduled push notification, this is the time the push notification will be triggered.

When a push notification is triggered, the server first looks up devices in the _Installation table that match the query condition, and then pushes the message to the devices. Because each _Installation is a key-value object that can contain custom attributes, you can implement complex conditions for sending push notifications, such as sending push notifications to users who are subscribed to specific channels or who are within a specific geographic area. You can also send push notifications to specific users.

Note the difference between devices and successes. If devices is 0, it means that there are no devices that match the conditions you specified. In this case, you need to check the conditions and see if they need to be changed. If devices is not 0, its value indicates the number of devices found that match the conditions you specified, but it’s not guaranteed that those devices will receive push notifications. It’s likely that successes will be less than devices. If there are a large number of inactive devices, there may be a large difference between successes and devices.

To prevent a device from receiving push notifications, change the valid attribute of the object for that device in the _Installation table to false.

Note that we only keep push records for one week, and will remove push records that were created more than a week ago. Even if a push record is removed, the push notifications it triggered will still be valid (and received by the target users) as long as they haven’t expired. For more information on how to set expiration times for push notifications, see 推送 REST API 使用指南.

Unity

See Unity Push Notification Guide.

iOS

See iOS Push Notification Guide.

Android

With the stricter permission controls enforced by Android, the deliverability of push notifications sent through the Push Notification service’s own channels has been negatively impacted. Therefore, we recommend that you send push notifications using mixpush. It integrates the interfaces provided by FCM so that you can trigger push notifications using a simple API. See Android Mixpush Guide for more information.

To learn more about Push Notification’s own channels, see Android Push Notification Guide.

Sending Push Notifications With REST API

See Push Notification REST API.

Sending Push Notifications With JavaScript SDK in Cloud Engine

The JavaScript SDK also provides an interface for sending push notifications, although it is primarily used in Cloud Engine. See the SDK’s API documentation (AV.Push) for more information. Here are two simple examples:

To send push notifications to all devices subscribed to the public channel:

AV.Push.send({
  channels: [ 'public' ],
  data: {
    alert: 'public message'
  }
});

To send push notifications to devices whose corresponding objects in the _Installation table match certain conditions, you can specify an AV.Query object as the where condition. For example, to send a push notification to an Android device that has a specific installationId:

const query = new AV.Query('_Installation');
query.equalTo('installationId', installationId);
AV.Push.send({
  where: query,
  data: {
    alert: 'Public message'
  }
});