API Documentation

Last updated: 2020-09-25 10:56:59

    Launching TPNS Service

    API description

    Launch the TPNS service by using the information of the application registered at the official website of TPNS. This is new in SDK v1.2.7.2 or above. For legacy versions, please see XGPush.h.

    /// @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: 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];

    Ending 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 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 parameter description

    • 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 of APNs.
    • error: error message. If error is nil, the push service has been successfully registered.

    Registering failure callback

    API description

    This callback is new in SDK 1.2.7.2 and used for TPNS registration failures.

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

    Account Feature

    Setting account

    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:

    1. This API should be called after xgPushDidRegisteredDeviceToken:error: returns a success.
    2. If you use a multi-account system, please see XGPush.h.
    - (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

    You can bind tags to different users and then push based on a specific tag.

    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 submit a ticket). 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 tabs.
    • type: operation type, which is XGPushTokenBindTypeTag for tag operations.

    Note:

    For tag operations, identifiers is a tag string array (the tag string cannot contain spaces or tabs).

    Sample code

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

    Updating tag

    API description

    This API is used to overwrite 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 ID string array. The tag string cannot contain spaces or tabs.
    • type: operation type, which is XGPushTokenBindTypeTag for tag operations.

    Note:

    identifiers is a tag string array (the tag string cannot contain spaces or tabs).

    • 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 clear 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 badge

    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 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 notification.

    - (void)deviceNotificationIsAllowed:(nonnull void (^)(BOOL isAllowed))handler;

    Parameter description

    handler: return method of query result.

    Sample code

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

    Querying SDK Version

    API description

    This API is used to query the current SDK version.

    - (nonnull NSString *)sdkVersion;

    Sample code

    [[XGPush defaultManager] sdkVersion];

    Log Reporting APIs

    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 1.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 accessId of the TPNS platform (SDK 1.2.5.3+).

    Sample code

    [XGForFreeVersion defaultForFreeVersion].freeAccessId = 2200262432;

    TPNS Log Hosting

    API description

    You can get TPNS logs by using this method, which has nothing to do with XGPush > enableDebug.

    Parameter description

    • logInfo Log information

    Sample code

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

    Customizing Notification Bar Message Action

    Creating message action

    API description

    Create a clickable event action in the notification message.

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

    Parameter description

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

    Sample code

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

    Note:

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

    Creating category object

    API description

    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 owned by the current category.
    • intentIdentifiers: used to indicate identifiers that can be recognized by Siri.
    • options: category characteristics.

    Note:

    The notification bar has the click event feature, which is only supported in iOS 8+. For iOS 8 or earlier, this method will return null.

    Sample code

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

    Creating configuration class

    API description

    Manage the style and characteristics of the push message notification bar.

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

    Parameter description

    • categories: collection of categories supported by the notification bar.
    • types: style of registered notification.

    Sample code

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

    Local Push

    For local push features, please see Apple developer documentation.

    Was this page helpful?

    Was this page helpful?

    • Not at all
    • Not very helpful
    • Somewhat helpful
    • Very helpful
    • Extremely helpful
    Send Feedback
    Help