API Documentation

Last updated: 2021-08-18 16:33:52

    Activating TPNS Service

    API description

    This API is used to launch the TPNS service by using the information of the application registered at the official website of TPNS.
    (This API is newly added in SDK v1.2.7.2. For v1.2.7.1 and below, please see the startXGWithAppID API in the XGPush.h file in the SDK package.)

    /// @note TPNS SDK1.2.7.2+
    - (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: the callback object.
    Note:

    The required API parameters must be entered correctly to use the TPNS service for message push to the application.

    Sample code

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

    Terminating TPNS Service

    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 callback is new in SDK v1.2.7.2 and used for TPNS registration failures.

    /// @note TPNS SDK1.2.7.2+
    - (void)xgPushDidFailToRegisterDeviceTokenWithError:(nullable NSError *)error
    

    Account Feature

    Creating accounts

    API description

    This API is used to set an account. If there is already a bound account, it will be overwritten; otherwise, the current account will be added.

    Note:


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

    - (void)updateBindedIdentifiers:(nonnull NSArray *)identifiers bindType:(XGPushTokenBindType)type;
    

    Parameter description

    • identifiers: account ID.
    • type: operation type, which is XGPushTokenBindTypeAccount for account operations.
    Note:

    • For account operations, a dictionary array is required, and the key is fixed.
    • Syntax for Objective-C: @[@{@"account":identifier, @"accountType":@(0)}].
    • Syntax for Swift: [["account":identifier, "accountType":NSNumber(0)]].
    • For more accountType values, please see the enumerated values of XGPushTokenAccountType.

    Sample code

    // Set an account:
    [[XGPushTokenManager defaultTokenManager] updateBindedIdentifiers:@[@{@"account" : identifier, @"accountType" : @(0)}]
    bindType:XGPushTokenBindTypeAccount];
    

    Clearing account

    API description

    This API is used to clear all set accounts.

    Note:

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

    - (void)clearAllIdentifiers:(XGPushTokenBindType)type;
    

    Parameter description
    type: operation type, which is XGPushTokenBindTypeAccount for account operations.

    Sample code

    [[XGPushTokenManager defaultTokenManager] clearAllIdentifiers:XGPushTokenBindTypeAccount];
    

    Tagging Feature

    Binding/Unbinding tag

    API description

    This API is used to bind tags to different users so that push can be performed based on specific 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 up to 100 custom tags (if you want to increase this limit, please contact customer service). One custom tag can be bound to an unlimited number of device tokens.

    Operation APIs

    - (void)bindWithIdentifiers:(nonnull NSArray *)identifiers type:(XGPushTokenBindType)type;
    - (void)unbindWithIdentifers:(nonnull NSArray *)identifiers type:(XGPushTokenBindType)type;
    

    Parameter description

    • identifiers: specifies the ID to be bound. The tag string cannot contain spaces or tab characters.
    • type: operation type, which is XGPushTokenBindTypeTag for tag operations.
    Note:

    For tag operations, identifiers is a tag string array, which cannot contain spaces or tab characters.

    Sample code

    // Bind tags
    [[XGPushTokenManager defaultTokenManager] bindWithIdentifiers:@[identifier] type:XGPushTokenBindTypeTag];
    // Unbind tags
    [[XGPushTokenManager defaultTokenManager] unbindWithIdentifers:@[identifier] type:XGPushTokenBindTypeTag];
    

    Updating tag

    API description

    This API is used to override the original tag. If no tag was previously bound, this API will add a tag.

    Note:

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

    - (void)updateBindedIdentifiers:(nonnull NSArray *)identifiers bindType:(XGPushTokenBindType)type;
    

    Parameter description

    • identifiers: tag identifier string array. The tag string cannot contain spaces or tab characters.
    • type: operation type, which is XGPushTokenBindTypeTag for tag operations.
    Note:

    identifiers is a tag identifier string array. The tag string cannot contain spaces or tab characters.

    • This API will replace all the old tags corresponding to the current token with the current tag.

    Clearing all tags

    API description

    This API is used to delete all set tags.

    Note:

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

    - (void)clearAllIdentifiers:(XGPushTokenBindType)type;
    

    Parameter description

    • type: operation type, which is XGPushTokenBindTypeTag for tag operations.

    Sample code

    [[XGPushTokenManager defaultTokenManager] clearAllIdentifiers:XGPushTokenBindTypeTag];
    

    Badge Feature

    Syncing badges

    API description

    When the local badge number is changed for the application, you need to call this API to sync it to the TPNS server, which will be used as the basis for the next push. This feature is in the console > Create Push > Advanced Settings > Badge Number.

    - (void)setBadge:(NSInteger)badgeNumber;
    

    Parameter description

    badgeNumber: badge number of an application

    Note:

    Note: when the local badge number is set for the application, you need to 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 exceptions with push, you can call this API to trigger reporting of local push logs. When feeding back the problem, please provide the file address for us to troubleshoot.

    /// @note TPNS SDK1.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];
    

    Unregistering XG Platform Service

    API description

    Background: if the application push service is migrated from the XG platform (https://xg.qq.com) to the TPNS platform, duplicate messages may appear when pushing on both platform at the same time. Therefore, you need to call the API of TPNS SDK(1.2.5.3+) to unregister the device information on the XG platform.
    Import the header file XGForFreeVersion.h and call before startXGWithAccessID:

    @property uint32_t freeAccessId;
    

    Parameter description

    • @freeAccessId: the AccessID obtained by registering the application on the XG platform (SDK 1.2.5.3+).

    Sample code

    [XGForFreeVersion defaultForFreeVersion].freeAccessId = 2200262432;
    

    TPNS Log Hosting

    API description

    This API is used to get TPNS logs, which has nothing to do with 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 or 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 versions later than iOS 8.0. For iOS 8.0 or earlier versions, 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 local push-related features, see Apple developer documentation.