API Documentation

Last updated: 2019-11-13 15:33:30

PDF

SDK API Description

Launching TPNS

Note

  • Launch TPNS by using the information of the app registered at the official TPNS website

API

- (void)startXGWithAppID:(uint32_t)appID appKey:(nonnull NSString *)appKey delegate:(nullable id<XGPushDelegate>)delegate ;

Parameter description

  • appID: App ID applied through the frontend, i.e., the Access ID
  • appKey: appKey applied through the frontend, i.e., the Access Key
  • 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 app.

Sample

[[XGPush defaultManager] startXGWithAppID: <#your access ID#>appKey:<#your access key#> delegate:<#your delegate#>];

Stopping the TPNS Service

Note

  • After the TPNS service is stopped, the app will not be able to push messages to devices through TPNS. To receive messages pushed by TPNS again, you must call startXGWithAppID:appKey:delegate: again to restart the TPNS service.

API

- (void)stopXGNotification;

Sample

[[XGPush defaultManager] stopXGNotification];

Customizing notification panel message action

Creating a message action

Note

Create a clickable event action in the notification

API

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

Parameter description

  • identifier: Unique action identifier
  • title: Action name
  • options: Options supported by the action

Sample

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

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

Creating a category object

Note

Create a category object to manage the action object of the notification panel

API

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

Parameter description

  • identifier: The identifier of the category object
  • actions: The action object group owned by the current category
  • intentIdentifiers: Used to indicate identifiers that can be recognized by Siri
  • options: The characteristics of the category

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

Sample

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

Creating a configuration class

Manage the style and characteristics of the push message notification panel

API

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

Parameter description

  • categories: The collection of categories supported by the notification panel
  • types: The style of the registered notification

Sample

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

Reporting Location

Note

  • Report the geographical location, and later use TPNS to send targeted push based on specific locations

API

- (void)reportLocationWithLatitude:(double)latitude longitude:(double)longitude;

Parameter description

  • latitude: Latitude
  • longitude: Longitude

Sample

[[XGPush defaultManager] reportLocationWithLatitude:20.0 longitude:19.0];

Automatically increasing badge number by 1

Note

  • Call this API to report the current app badge number to the TPNS server. After the client is configured, you can use the "automatically increasing badge number by 1" feature, which can be found in the console (create a push > notification panel message > general settings > badge number)

API

- (void)setBadge:(NSInteger)badgeNumber;

Parameter description

  • badgeNumber, badge number of the app

**Note:

  1. This API must be called locally, otherwise the badge number by default will not change, even if the "automatically increasing badge number by 1" feature is enabled.

**

Sample

[[XGPush defaultManager] setBadge:7];

Managing app badge

Note

  • Manage the badge number displayed by the app

API

@property (nonatomic) NSInteger xgApplicationBadgeNumber;

Sample

// Set the app badge
[[XGPush defaultManager] setXgApplicationBadgeNumber:0];

// Get the app badge
NSInteger number = [[XGPush defaultManager] xgApplicationBadgeNumber];

Push effect statistics

Note

  • In order to better understand the operational effect of each push message, it is necessary to report the user action on the message

The data reporting API needs to be called
API

- (void)reportXGNotificationInfo:(nonnull NSDictionary *)info;

Sample

- (BOOL)application:(UIApplication *)application
  didFinishLaunchingWithOptions:(NSDictionary *)launchOptions 
  {
      [[XGPush defaultManager] reportXGNotificationInfo:launchOptions];
      return YES;
  }
  • For iOS 9.x and earlier, you need to call the data reporting API in the callback method of UIApplicationDelegate (see below):
- (void)application:(UIApplication *)application 
    didReceiveRemoteNotification:(NSDictionary *)userInfo 
        fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler 
{ 
}

Sample

- (void)application:(UIApplication *)application 
    didReceiveRemoteNotification:(NSDictionary *)userInfo 
        fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler 
{
    [[XGPush defaultManager] reportXGNotificationInfo:userInfo];
    completionHandler(UIBackgroundFetchResultNewData);
}
  • For iOS 10.0+, you need to call the data reporting API in the callback method of XGPushDelegate (see below):

Sample

 - (void)xgPushUserNotificationCenter:(UNUserNotificationCenter *)center
   didReceiveNotificationResponse:(UNNotificationResponse *)response
   withCompletionHandler:(void(^)())completionHandler 
   {

    [[XGPush defaultManager] reportXGNotificationResponse:response];
            completionHandler();

   }

If you want to enable the app to display the push message in the foreground, you need to implement the following method and call the reporting API

API

- (void)xgPushUserNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler;

Sample

- (void)xgPushUserNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(UNNotificationPresentationOptions))completionHandler {
    [[XGPush defaultManager] reportXGNotificationInfo:notification.request.content.userInfo];
    completionHandler(UNNotificationPresentationOptionBadge | UNNotificationPresentationOptionSound | UNNotificationPresentationOptionAlert);
}

Managing device token

Querying device token

Note

  • Query the Token string obtained from APNs by the current app

API

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

Sample

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

Querying APNs registration result

Note

  • If the registration is successful, the app will call the callback method of the UIApplicationDelegate delegate object (see below):

API

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken;

Querying TPNS registration result

Note

  • The SDK startup method automatically registers the Token obtained by the device from APNs to the TPNS server, and the registration result will be returned in the callback method of XGPushDelegate (see below):

API

- (void)xgPushDidRegisteredDeviceToken:(NSString *)deviceToken error:(NSError *)error;

Note: This callback method is called after the registration is successful. After the current Token is registered, the SDK will cache the registration information, and this method will not be called again

Binding/Unbinding tag and account

Note

  • You can bind tags to different users and then push based on a specific tag, i.e., if you push to a tag, all devices under the tag will receive the push. One device can bind multiple tags.

Single-operation API

- (void)bindWithIdentifier:(nullable NSString *)identifier type:(XGPushTokenBindType)type;
- (void)unbindWithIdentifer:(nullable NSString *)identifier type:(XGPushTokenBindType)type;

Parameter description

  • identifier: Tag or account
  • type: Binding type

Sample

// Bind the tag:
[[XGPushTokenManager defaultTokenManager] bindWithIdentifier:@"your tag" type:XGPushTokenBindTypeTag];

// Unbind the tag
[[XGPushTokenManager defaultTokenManager] unbindWithIdentifer:@"your tag" type:XGPushTokenBindTypeTag];

// Bind an account:
[[XGPushTokenManager defaultTokenManager] bindWithIdentifier:@"your account" type:XGPushTokenBindTypeAccount];

//Unbind an account:
[[XGPushTokenManager defaultTokenManager] unbindWithIdentifer:@"your account" type:XGPushTokenBindTypeAccount];

Batch operation API

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

Parameter description

  • identifiers: List of tags or accounts
  • type: Binding type

Note

  • Account type is currently not supported. The tag string cannot contain spaces or tabs

Batch updating tags/accounts

API

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

Parameter description

  • identifiers: Tag identifier string array. The tag string cannot contain spaces or tabs
  • type: Identifier type

Note

  • If the tag type is specified, this API will replace all the old tag corresponding to the current Token with the current tag; if the account type is specified, this API will only take the first one in the identifier list

Clearing all tags/accounts

API

- (void)clearAllIdentifiers:(XGPushTokenBindType)type;

Parameter description

  • type: Identifier type

Querying tags and accounts bound to the token

Note

  • Query the identifier bound to the current Token object according to the specified type

API

- (nullable NSArray<NSString *> *)identifiersWithType:(XGPushTokenBindType)type;

Sample

// Query the tag
[[XGPushTokenManager defaultTokenManager] identifiersWithType:XGPushTokenBindTypeTag];
// Query the account
[[XGPushTokenManager defaultTokenManager] identifiersWithType:XGPushTokenBindTypeAccount];

Querying device notification permission

Note

  • Query whether the user allows device notification

API

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

Parameter description

  • handler: The return method of the query result

Sample

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

Querying SDK version

Note

  • Query the current SDK version

API

- (nonnull NSString *)sdkVersion;

Sample

[[XGPush defaultManager] sdkVersion];

Local Push

For local push-related features, see Apple developer documentation.