tencent cloud

Tencent Push Notification Service

Release Notes
Announcements
Features
SDK for Android
SDK for iOS
SDK for macOS
Product Introduction
Overview
Strengths
Use Cases
Global Deployment
Purchase Guide
Billing Overview
Purchase Directions
Billing Modes
Free Trial
Payment Overdue
Getting Started
Creating Products and Applications
Quick Integration with Android
Quick Integration with iOS
Creating a Push Task
Querying Push Records
Guidelines for Push Testing Methods
Product Restrictions
Operation Guide
Push Management
Advanced Push Features
Practical Tutorial
iOS Badge Feature Practice
API Documentation
Overview
API Overview
Call Method
Push APIs
Tag APIs
Account APIs
Statistics APIs
User Attribute APIs
Server-Side Error Codes
Server SDKs
API (Java)
SDK Documentation
Android Integration Guide
iOS Integration Guide
Client Integration Plugin
macOS Integration Guide
Users and Permissions
Quick Configuration
Advanced Custom Configuration
Resource Tag
Service Agreement
Service Level Agreement
FAQs
iOS
Android
Flutter
Others
Tencent Push Notification Service Policy
Privacy Policy
Data Processing and Security Agreement
Developer Agreement
Contact Us
Glossary
DocumentationTencent Push Notification ServiceSDK DocumentationmacOS Integration GuideAPI Documentation

API Documentation

PDF
Focus Mode
Font Size
Last updated: 2024-11-20 16:59:51

Launching the TPNS Service

The following are device registration API methods. For more information on the timing and principle of calls, see Device registration flow.

API description

Launch the TPNS service by using the information of the application registered at the official website of TPNS.
- (void)startXGWithAccessID:(uint32_t)accessID accessKey:(nonnull NSString *)accessKey delegate:(nullable id<XGPushDelegate>)delegate;

Parameter description

accessID: AccessID applied through the frontend
accessKey: AccessKey applied through the frontend
Delegate: callback object
Note:
The parameters required by the API must be entered correctly; otherwise, TPNS will not be able to push messages correctly for the application.

Sample code

 [[XGPush defaultManager] startXGWithAccessID:<your AccessID> accessKey:<your AccessKey> delegate:self];

Terminating the TPNS Service

The following are device unregistration API methods. For more information on the timing and principle of calls, please see Device unregistration flow.

API description

After the TPNS service is stopped, the application will not be able to push messages to devices through TPNS. To receive messages pushed by TPNS again, you must call the startXGWithAccessID:accessKey:delegate: method again to restart the TPNS service.
- (void)stopXGNotification;

Sample code

[[XGPush defaultManager] stopXGNotification];

TPNS Token and Registration Result

Querying the TPNS token

API description

This API is used to query the token string generated by the current application on the TPNS server.
@property (copy, nonatomic, nullable, readonly) NSString *xgTokenString;

Sample code

NSString *token = [[XGPushTokenManager defaultTokenManager] xgTokenString];

Registration result callback

API description

After the SDK is started, use this method callback to return the registration result and token.
- (void)xgPushDidRegisteredDeviceToken:(nullable NSString *)deviceToken xgToken:(nullable NSString *)xgToken error:(nullable NSError *)error

Response parameters

deviceToken: device token generated by APNs.
xgToken: token generated by TPNS, which needs to be used during message push. TPNS maintains the mapping relationship between this value and the device token generated by APNs.
error: error message. If error is nil, TPNS has been successfully registered.

Registration failure callback

API description

This is a callback for TPNS registration failures.
- (void)xgPushDidFailToRegisterDeviceTokenWithError:(nullable NSError *)error

Notification pop-up window authorization callback

API description

This is a callback for notification pop-up window authorization results.
- (void)xgPushDidRequestNotificationPermission:(bool)isEnable error:(nullable NSError *)error;

Response parameters

isEnable: whether authorization is approved or not.
error: error message. If error is nil, the pop-up authorization result has been successfully obtained.

Account Feature

The following are account API methods. For more information on the timing and principle of calls, please see Account flow.

Adding an account

API description

If there is no account of this type, it will add a new one; otherwise, it will overwrite the existing one.
- (void)upsertAccountsByDict:(nonnull NSDictionary<NSNumber *, NSString *> *)accountsDict;
Note:
This API should be called after xgPushDidRegisteredDeviceToken:error: returns a success.

Parameter description

accountsDict: account dictionary
Note:
The account type and account name together serve as the composite primary key.
You need to use the dictionary type, where key is the account type and value is the account, for example, @{@(accountType):@"account"}.
Syntax for Objective-C: @{@(0):@"account0",@(1):@"account1"}; syntax for Swift:[NSNumber(0):@"account0",NSNumber(1):@"account1"]
For more accountType values, see the XGPushTokenAccountType enumeration in the SDK demo package or Account Type Value Table.

Sample code

XGPushTokenAccountType accountType = XGPushTokenAccountTypeUNKNOWN;
NSString *account = @"account";
[[XGPushTokenManager defaultTokenManager] upsertAccountsByDict:@{ @(accountType):account }];

Adding a mobile number

API description

This API is used to add or update a mobile number. It is equivalent to calling upsertAccountsByDict:@{@(1002):@"specific mobile number"}.
- (void)upsertPhoneNumber:(nonnull NSString *)phoneNumber;

Parameter description

phoneNumber: an E.164 mobile number in the format of [+][country code or area code][mobile number], for example, +8613711112222. The SDK will encrypt the mobile number for transmission.

Sample code

[[XGPushTokenManager defaultTokenManager] upsertPhoneNumber:@"13712345678"];;

Note:
1. This API should be called after xgPushDidRegisteredDeviceToken:error: returns a success.
2. You can call delAccountsByKeys:[[NSSet alloc] initWithObjects:@(1002), nil] to delete a mobile number.

Deleting accounts

API description

This API is used to delete all accounts of a specified account type.
- (void)delAccountsByKeys:(nonnull NSSet<NSNumber *> *)accountsKeys;

Note:
This API should be called after xgPushDidRegisteredDeviceToken:error: returns a success.

Parameter description

accountsKeys: set of account types
Note:
A set is required, and the key is fixed.
For more values of accountType, please see the enumerated values of XGPushTokenAccountType in the XGPush.h file in the SDK package.

Sample code

XGPushTokenAccountType accountType = XGPushTokenAccountTypeUNKNOWN;

NSSet *accountsKeys = [[NSSet alloc] initWithObjects:@(accountType), nil];

[[XGPushTokenManager defaultTokenManager] delAccountsByKeys:accountsKeys];


Clearing accounts

API description

This API is used to clear all set accounts.
- (void)clearAccounts;
Note:
This API should be called after xgPushDidRegisteredDeviceToken:error: returns a success.

Sample code

[[XGPushTokenManager defaultTokenManager] clearAccounts];

Tag Feature

The following are tag API methods. For more information on the timing and principle of calls, please see Tag flow.

Binding/Unbinding tags

API description

This API is used to bind tags to different users so that push can be performed based on specific tags.
- (void)appendTags:(nonnull NSArray<NSString *> *)tags
- (void)delTags:(nonnull NSArray<NSString *> *)tags
Note:
This API works in an appending manner.
This API should be called after xgPushDidRegisteredDeviceToken:error: returns a success.
One application can have up to 10,000 custom tags. One device token can be bound to a maximum of 100 custom tags (if you want to increase this limit, please submit a ticket). One custom tag can be bound to an unlimited number of device tokens.

Parameter description

tags: tag array
Note:
For tag operations, tags is a tag string array, which cannot contain spaces or tabs.

Sample code

// Bind tags
[[XGPushTokenManager defaultTokenManager] appendTags:@[ tagStr ]];

// Unbind tags
[[XGPushTokenManager defaultTokenManager] delTags:@[ tagStr ]];

Updating tags

API description

This API is used to clear all the existing tags and then add tags in batches.
- (void)clearAndAppendTags:(nonnull NSArray<NSString *> *)tags
Note:
This API should be called after xgPushDidRegisteredDeviceToken:error: returns a success.
This API will replace all the old tags corresponding to the current token with the current tag.

Parameter description

tags: tag array
Note:
For tag operations, tags is a tag string array, which cannot contain spaces or tabs.

Sample code

[[XGPushTokenManager defaultTokenManager] clearAndAppendTags:@[ tagStr ]];

Clearing all tags

API description

This API is used to clear all set tags.
- (void)clearTags
Note:
This API should be called after xgPushDidRegisteredDeviceToken:error: returns a success.

Sample code

[[XGPushTokenManager defaultTokenManager] clearTags];


Querying tags

API description

This API is used to query tags bound to a device.
- (void)queryTags:(NSUInteger)offset limit:(NSUInteger)limit;
Note:
This API should be called after xgPushDidRegisteredDeviceToken:error: returns a success.

Parameter description

offset: the offset of this query
limit: the page size for this query; maximum value: 200

Sample code

 [[XGPushTokenManager defaultTokenManager] queryTags:0 limit:100];

Tag query callback

API description

This is a callback for tag query results.
- (void)xgPushDidQueryTags:(nullable NSArray<NSString *> *)tags totalCount:(NSUInteger)totalCount error:(nullable NSError *)error;

Response parameters

tags: tags returned for the query
totalCount: total number of the tags bound to the device
error: error message. If error is nil, the query is successful.

User Attribute Feature

The following are user attribute API methods. For more information on the timing and principle of calls, please see User attribute flow.

Adding user attributes

API description

This API is used to add or update user attributes in the key-value structure (if there is no user attribute value corresponding to the key, it will add a new one; otherwise, it will update the value).
- (void)upsertAttributes:(nonnull NSDictionary<NSString *,NSString *> *)attributes
Note:
This API should be called after xgPushDidRegisteredDeviceToken:error: returns a success.

Parameter description

attributes: dictionary of user attribute strings, which cannot contain spaces or tabs.
Note:
You need to configure user attribute keys in the console first before the operation can succeed.
Both key and value can contain up to 50 characters.
A dictionary is required, and key is fixed.
Objective-C syntax: @{@"gender": @"Female", @"age": @"29"}
Syntax for Swift: ["gender":"Female", "age": "29"]

Sample code

[[XGPushTokenManager defaultTokenManager] upsertAttributes:attributes];

Deleting user attributes

API description

The API is used to delete existing user attributes.
- (void)delAttributes:(nonnull NSSet<NSString *> *)attributeKeys
Note:
This API should be called after xgPushDidRegisteredDeviceToken:error: returns a success.

Parameter description

attributeKeys: set of user attribute keys, which cannot contain spaces or tabs.
Note:
A set is required and the key is fixed.

Sample code

[[XGPushTokenManager defaultTokenManager] delAttributes:attributeKeys];

Clearing all user attributes

API description

This API is used to clear all existing user attributes.
- (void)clearAttributes;
Note:
This API should be called after xgPushDidRegisteredDeviceToken:error: returns a success.

Sample code

[[XGPushTokenManager defaultTokenManager] clearAttributes];

Updating user attributes

API description

This API is used to clear all the existing user attributes and then add user attributes in batches.
- (void)clearAndAppendAttributes:(nonnull NSDictionary<NSString *,NSString *> *)attributes
Note:
This API should be called after xgPushDidRegisteredDeviceToken:error: returns a success.

Sample code

[[XGPushTokenManager defaultTokenManager] clearAndAppendAttributes:attributes];

Badge Feature

Syncing badges

API description

This API is used to sync the modified local badge value of an application to the TPNS server for the next push. You can choose Create Push > Advanced Settings > Badge Number in the console to configure the badge number.
- (void)setBadge:(NSInteger)badgeNumber;

Parameter description

badgeNumber: badge number of an application
Note:
After the local badge number is set for the application, call this API to sync it to the TPNS server, which will take effect in the next push. This API must be called after successful TPNS registration (xgPushDidRegisteredDeviceToken).

Sample code

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
    /// Zero the badge number every time the application is started (you should set the local badge number for the application in the main thread)
    if ([XGPush defaultManager].xgApplicationBadgeNumber > 0) {
        [XGPush defaultManager].xgApplicationBadgeNumber = 0;
    }
    return YES;
}

- (void)xgPushDidRegisteredDeviceToken:(nullable NSString *)deviceToken xgToken:(nullable NSString *)xgToken error:(nullable NSError *)error {
    /// Sync the badge number to TPNS after registration
    if (!error) {
        [[XGPush defaultManager] setBadge:0];
    }
}

Querying device notification permission

API description

This API is used to query whether the user allows device notifications. 
- (void)deviceNotificationIsAllowed:(nonnull void (^)(BOOL isAllowed))handler;

Parameter description

handler: result return method

Sample code

[[XGPush defaultManager] deviceNotificationIsAllowed:^(BOOL isAllowed) {
        <#code#>
    }];

Querying the SDK Version

API description

This API is used to query the current SDK version.
- (nonnull NSString *)sdkVersion;

Sample code

[[XGPush defaultManager] sdkVersion];

Log Reporting API

API description

If you find push exceptions, you can call this API to trigger reporting of local push logs. To report the problem, submit a ticket with the file address provided to facilitate troubleshooting.
- (void)uploadLogCompletionHandler:(nullable void(^)(BOOL result,  NSString * _Nullable errorMessage))handler;

Parameter description

@brief: report log information
@param handler: report callback

Sample code

[[XGPush defaultManager] uploadLogCompletionHandler:nil];

TPNS Log Hosting

API description

This method is used to get TPNS logs, which is irrelevant to XGPush > enableDebug.

Parameter description

logInfo: log information

Sample code

- (void)xgPushLog:(nullable NSString *)logInfo;

Local Push

For more information about the local push feature, please click here.
Previous Topic: SDK IntegrationNext Topic: Push Certificate Description

Help and Support

Was this page helpful?

Help us improve! Rate your documentation experience in 5 mins.

Feedback