API Documentation

Last updated: 2020-12-01 14:49:18

    Description

    This document contains such features as the push, tag and user attributes that are applicable to SDK 1.2.8.0 or later. For **SDK 1.2.7.2 or earlier versions, please see here.

    Activating TPNS Service

    API description

    This API is used to activate TPNS by using the information of the application registered on the TPNS Console.
    (This is new in SDK 1.2.7.2 or later. For legacy versions, use the startXGWithAppID API in the XGPush.h file of 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: the AccessID obtained by registering the application on the console.
    • accessKey: the AccessKey obtained by registering the application on the console.
    • 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];

    Ending TPNS Service

    API description

    After the TPNS service is stopped, TPNS no longer pushes messages to devices. To receive the push messages again, please use the startXGWithAccessID:accessKey:delegate: method again to restart the TPNS service.

    - (void)stopXGNotification;

    Sample code

    [[XGPush defaultManager] stopXGNotification];

    TPNS Token and Registration

    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 enabled, use this callback method to return the registration result and token.

    - (void)xgPushDidRegisteredDeviceToken:(nullable NSString *)deviceToken xgToken:(nullable NSString *)xgToken error:(nullable NSError *)error

    Response parameters

    • deviceToken: the Device Token generated by APNs.
    • xgToken: the Token generated on TPNS, which needs to be used during message push. TPNS maintains the mapping relationship between this value and the Device Token of APNs.
    • error: the error message. If error is nil, it indicates that the push service has been successfully registered.

    Registration 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

    Creating accounts

    API description

    This API is used to delete all accounts and batch add accounts.

    - (void)clearAndAppendAccounts:(nonnull NSArray<NSDictionary *> *)accounts;

    Note:

    • This API should be called after xgPushDidRegisteredDeviceToken:error: returns a success.
    • Due to the low use and easy confusion, the appendAccounts API is scheduled to be disused since October 26. The earlier use of the API is to overwrite accounts.

    Parameter description

    • accounts: the array of accounts.

    Note:

    • One account supports binding up to 100 tokens.
    • Use a dictionary in key-value pairs for account operations and use account as a fixed key.
    • Syntax for Objective-C: @[@{@"accountType":@(0),@"account":identifier}];
    • Syntax for Swift: [["accountType":NSNumber(0),"account":identifier]]
    • For more accountType values, see the enumerated values of XGPushTokenAccountType in the XGPush.h file of the SDK package.

    Sample code

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

    Deleting accounts

    API description

    This API is used to delete all existing accounts.

    Note:

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

    - (void)clearAccounts;

    Sample code

    [[XGPushTokenManager defaultTokenManager] clearAccounts];

    Tag Feature

    Binding/unbinding a tag

    API description

    This API is used to bind a tag to different users for the tag push.

    Note:

    • This API will add and bind tags.
    • 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.

    Operation APIs

    - (void)appendTags:(nonnull NSArray<NSString *> *)tags
    - (void)delTags:(nonnull NSArray<NSString *> *)tags

    Parameter description

    • tags: the array of tags.

    Note:

    The tags is a tag string array, which cannot contain spaces or tabs.

    Sample code

    // Bind a tag:
    [[XGPushTokenManager defaultTokenManager] appendTags:@[ tagStr ]];
    
    // Unbind a tag
    [[XGPushTokenManager defaultTokenManager] delTags:@[ tagStr ]];

    Updating a tag

    API description

    This API is used to delete all tags and batch add tags.

    Note:

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

    - (void)clearAndAppendTags:(nonnull NSArray<NSString *> *)tags

    Parameter description

    • tags: the array of tags.

    Note:

    The tags is a tag string array, which cannot contain spaces or tabs.

    • This API will delete old tags bound to the current token and bind new tags.

    Sample code

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

    Deleting all tags

    API description

    This API is used to delete all existing tags.

    Note:

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

    - (void)clearTags

    Sample code

    [[XGPushTokenManager defaultTokenManager] clearTags];

    User Attribute Feature

    New user attributes

    API description

    This API is used to create or update existing key-value pairs for the user attribute.

    Note:

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

    - (void)upsertAttributes:(nonnull NSDictionary<NSString *,NSString *> *)attributes

    Parameter description

    • attributes: a dictionary in key-value pairs for user attribute strings, which cannot contain spaces or tabs.

    Note:

    • The keys must be first configured on the console.
    • Use a dictionary in key-value pairs for user attributes and use account as a fixed key.
    • 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 a user attribute.

    Note:

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

    - (void)delAttributes:(nonnull NSSet<NSString *> *)attributeKeys

    Parameter description

    • attributeKeys: a set of keys for user attributes. The string cannot contain spaces or tabs.

    Note:

    Use a data set and account as a fixed key.

    Sample code

    [[XGPushTokenManager defaultTokenManager] delAttributes:attributeKeys];

    Clearing user attributes

    API description

    This API is used to delete all user attributes.

    Note:

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

    - (void)clearAttributes;

    Sample code

    [[XGPushTokenManager defaultTokenManager] clearAttributes];

    Updating user attributes

    API description

    This API is used to delete all user attributes and batch add new ones.

    Note:

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

    - (void)clearAndAppendAttributes:(nonnull NSDictionary<NSString *,NSString *> *)attributes

    Sample code

    [[XGPushTokenManager defaultTokenManager] clearAndAppendAttributes:attributes];

    Badge Feature

    Syncing badge

    API description

    This API is used to sync the modified local badge value of the application to the TPNS server for the next push. You can go to Create Push-> Advanced Settings -> Badge Number on the console to configure badge number.

    - (void)setBadge:(NSInteger)badgeNumber;

    Parameter description

    badgeNumber: the badge number of the 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 {
        /// The badge number will be reset to zero 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

    Check whether the notification is enabled on the device.

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

    Parameter description

    handler: the result return method.

    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

    This API is used to report local logs if a push error occurs. Please provide the file address in a ticket submitted for the troubleshooting.

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

    TPNS Log Hosting

    API description

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

    Parameter description

    • logInfo: the log information.

    Sample code

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

    Customizing Notification Bar Message Action

    Creating a message action

    API description

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

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

    Parameter description

    • identifier: the unique action ID.
    • title: the action name.
    • options: the action content.

    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: the category object ID.
    • actions: the 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 or later. For versions earlier than iOS 8, 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, please click here.

    Was this page helpful?

    Was this page helpful?

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