tencent cloud

Notes

The account, tag, and user attribute features in this document are applicable to SDK v1.2.9.0 and later. For SDK v1.2.7.2 and earlier, see API Documentation.

Launching the Tencent Push Notification Service

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

API description

This API is used to launch the Tencent Push Notification Service by using the information of the application registered at the official website of Tencent Push Notification Service.
(This API is newly added in SDK v1.2.7.2. For v1.2.7.1 and earlier, see the startXGWithAppID API in the XGPush.h file in the SDK package.)

/// @note Tencent Push Notification Service SDK v1.2.7.2 or later
- (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, Tencent Push Notification Service 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 Tencent Push Notification Service

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

API description

After the Tencent Push Notification Service is stopped, the application will not be able to push messages to devices through it. To receive messages pushed by it again, you must call the startXGWithAccessID:accessKey:delegate: method again to re-activate the service.

- (void)stopXGNotification;

Sample code

[[XGPush defaultManager] stopXGNotification];

Tencent Push Notification Service Token and Registration Result

Querying a Tencent Push Notification Service token

API description

This API is used to query the token string generated by the current application on the Tencent Push Notification Service server.

@property (copy, nonatomic, nullable, readonly) NSString *xgTokenString;

Sample code

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

Note：

Token query should be called after xgPushDidRegisteredDeviceToken:error: returns a success.

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 Tencent Push Notification Service, which needs to be used during message push. Tencent Push Notification Service maintains the mapping relationship between this value and the device token generated by APNs.
• error: error message. If error is nil, Tencent Push Notification Service has been successfully registered.

Registration failure callback

API description

This callback is new in SDK v1.2.7.2 and used for Tencent Push Notification Service registration failures.

/// @note Tencent Push Notification Service SDK v1.2.7.2 or later
- (void)xgPushDidFailToRegisterDeviceTokenWithError:(nullable NSError *)error

Notification pop-up window authorization callback

API description

This API was added in SDK v1.3.1.0 and is used to call back the result of notification authorization pop-up window.

- (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, see Account flow.

Adding an account

API description

If there is no account of this type, this API will add a new one; otherwise, it will overwrite the existing one. (This API is available only in Tencent Push Notification Service SDK v1.2.9.0 or later.)

- (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"}.

/// @note Tencent Push Notification Service SDK v1.3.2.0+
- (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:@"+8613712345678"];;

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. (This API is available only in Tencent Push Notification Service SDK v1.2.9.0 or later.)

- (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, 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];

Tagging Feature

The following are tag API methods. For more information on the timing and principle of calls, 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 (to increase this limit, 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 new in SDK v1.3.1.0 and used to query the tags bound to the 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 API is new in SDK v1.3.1.0 and used to call back the result of tag query.

- (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, 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.
• Syntax for Objective-C: @{@"gender": @"Female", @"age": @"29"}
• Syntax for Swift: ["gender":"Female", "age": "29"]

Sample code

[[XGPushTokenManager defaultTokenManager] upsertAttributes:attributes];

Deleting a user attribute

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：

It is required to use a key set.

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 Tencent Push Notification Service 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：

When the local badge number is set for the application, you need to call this API to sync it to the Tencent Push Notification Service server, which will take effect in the next push. This API must be called after the Tencent Push Notification Service persistent connection is established successfully (xgPushNetworkConnected).

Sample code

/// Timing for calling a cold start
- (void)xgPushDidRegisteredDeviceToken:(nullable NSString *)deviceToken xgToken:(nullable NSString *)xgToken error:(nullable NSError *)error {
  /// Report the badge number after registration
  if (!error) {
   /// Reset the application badge. `-1`: Do not clear the notification bar; `0`: Clear the notification bar
   [XGPush defaultManager].xgApplicationBadgeNumber = -1;
      /// Reset the server badge base
      [[XGPush defaultManager] setBadge:0];
  }
}
/// Timing for calling a hot start
/// The hot start tag `_launchTag` is managed by the business.
- (void)xgPushNetworkConnected {
  if (_launchTag) {
      /// Reset the application badge. `-1`: Do not clear the notification bar; `0`: Clear the notification bar
      [XGPush defaultManager].xgApplicationBadgeNumber = -1;
      /// Reset the server badge base
      [[XGPush defaultManager] setBadge:0];
      _launchTag = NO;
  }
}

In-app message display

Polling time setting

API description

This API can be used to set the polling time (minimum: 10s; default: 258s) of in-app messages.

/// Set the message polling time interval (minimum: 10s). This API should be called before the singleton initialization.
- (void)setMessageTimerInterval:(NSTimeInterval)interval;

Parameter description

NSTimeInterval: NSTimeInterval type; the in-app message polling time interval

Custom event handling

XGInAppMessageActionDelegate proxy description

You can obtain custom event parameters through the proxy method onClickWithCustomAction to handle related businesses.

/// Button event response proxy
@property (weak, nonatomic, nullable) id<XGInAppMessageActionDelegate> actionDelegate;

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 the reporting of local push logs. When you submit a ticket to report the problem, provide us the file address to facilitate troubleshooting.

/// @note Tencent Push Notification Service SDK v1.2.4.1+
- (void)uploadLogCompletionHandler:(nullable void(^)(BOOL result,  NSString * _Nullable errorMessage))handler;

Parameter description

• @brief: report log information (SDK v1.2.4.1+).
• @param handler: report callback

Sample code

[[XGPush defaultManager] uploadLogCompletionHandler:nil];

Tencent Push Notification Service Log Hosting

API description

This method is used to get Tencent Push Notification Service logs, which is irrelevant to XGPush > enableDebug.

Parameter description

logInfo: log information

Sample code

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

Customizing Notification Bar Message Actions

Creating a message action

API description

This API is used to create a click event in the notification message.

+ (nullable id)actionWithIdentifier:(nonnull NSString *)identifier title:(nonnull NSString *)title options:(XGNotificationActionOptions)options;

Parameter description

• identifier: unique ID of the action.
• title: action name.
• options: options supported by the action.

Sample code

XGNotificationAction *action1 = [XGNotificationAction actionWithIdentifier:@"xgaction001" title:@"xgAction1" options:XGNotificationActionOptionNone];

Note：

The notification bar has the event click feature, which is only supported in iOS 8.0 and later. For iOS 7.x or earlier, this method will return null.

Creating a category object

API description

This API is used to create a category object to manage the action object of the notification bar.

+ (nullable id)categoryWithIdentifier:(nonnull NSString *)identifier actions:(nullable NSArray<id> *)actions intentIdentifiers:(nullable NSArray<NSString *> *)intentIdentifiers options:(XGNotificationCategoryOptions)options

Parameter description

• identifier: category object ID.
• actions: action object group included in the current category.
• intentIdentifiers: identifiers that can be recognized by Siri.
• options: category characteristics.

Note：

The notification bar has the event click feature, which is only supported in iOS 8.0 and later. For versions earlier than iOS 8.0, this method will return null.

Sample code

XGNotificationCategory *category = [XGNotificationCategory categoryWithIdentifier:@"xgCategory" actions:@[action1, action2] intentIdentifiers:@[] options:XGNotificationCategoryOptionNone];

Creating a configuration class

API description

This API is used to manage the style and characteristics of the push message notification bar.

+ (nullable instancetype)configureNotificationWithCategories:(nullable NSSet<id> *)categories types:(XGUserNotificationTypes)types;

Parameter description

• categories: a collection of categories supported by the notification bar.
• types: the style of the device registration notification.

Sample code

XGNotificationConfigure *configure = [XGNotificationConfigure configureNotificationWithCategories:[NSSet setWithObject:category] types:XGUserNotificationTypeAlert|XGUserNotificationTypeBadge|XGUserNotificationTypeSound];

Local Push

For more information about the local push feature, click here.