SDK Integration

Last updated: 2020-07-22 11:50:54


    This document provides sample code for integrating with the SDK and launching TPNS. (SDK version: v1.0+)


    If you are migrating from the XG Platform to TPNS, please be sure to:

    1. Unregister XG platform service API.
    2. Implement corresponding changes based on the application integration conditions as instructed in the iOS migration guide and then return to this document.
    3. Complete the integration as described below.

    SDK Composition

    • doc folder: TPNS SDK for iOS development guide.
    • demo folder: it contains demo projects and TPNS SDK (only the OC demo is included. For the Swift demo, please go to TGit).

    SDK Integration

    Preparations for integration

    1. Before integrating the SDK, please log in to the TPNS Console and create the product and iOS application. For detailed directions, please see Creating Products and Applications.
    2. Once the application is created, you can apply for trial for it as instructed in Applying for Trial .
    3. Click Configuration Management to enter the management page.
    4. Click Upload Certificate to complete the upload. For more information on how to get a push certificate, please see Acquisition of Push Certificate.
    5. After the certificate is uploaded, get Access ID and Access KEY from the application information column.

    SDK import (three methods)

    Method 1. Import through Cocoapods

    Download through Cocoapods:

    pod 'TPNS-iOS' 


    • For the first download, you need to log in to the git address to set the username and password in Account. After successful configuration, enter the corresponding username and password in Terminal. Subsequently, no login is required on the current PC.
    • Due to the change of the git address, if the pod prompts Unable to find a specification for 'TPNS-iOS', you need to run the following command to update the git and confirm the version:
    pod repo update
    pod search TPNS-iOS
    pod install // Install the SDK 

    Method 2. Import through carthage

    Specify the dependent third-party libraries in the Cartfile file:

    github "xingePush/carthage-TPNS-iOS"

    Method 3. Import manually

    1. Enter the TPNS Console and click SDK Download on the left sidebar to go to the download page. Select the SDK version to download and click Download in the "Operation" column.
    2. Open the SDK folder under the demo directory. Add XGPush.h and libXG-SDK-Cloud.a to the project. Open the ---XGPushStatistics folder and get XGMTACloud.framework.
    3. Add the following frameworks to Build Phases:
      * XGMTACloud.framework
      * CoreTelephony.framework
      * SystemConfiguration.framework
      * UserNotifications.framework
      * libXG-SDK-Cloud.a 
      * libz.tbd
      * CoreData.framework
      * CFNetwork.framework
      * libc++.tbd
    4. After the frameworks are added, the library references are as follows:

    Project configuration

    1. Enabled Push Notifications in Project Configuration and Background Modes as shown below:
    2. Add the compilation parameter -ObjC .

      If checkTargetOtherLinkFlagForObjc reports an error, it means that -ObjC has not been added to Other link flags in build setting.


    If your application service access point is Guangzhou, the SDK implements this configuration by default.
    If your application service access point is Singapore or Hong Kong (China), please follow the steps below to complete the configuration.

    1. Decompress the SDK file package and add the XGPushPrivate.h file in the SDK directory to the project.
    2. Call the domain name configuring API in the header file before calling the startXGWithAppID method:
      To integrate with the Singapore service access point, set domain name to


     [[XGPush defaultManager] configureClusterDomainName:@""];

    To integrate with the Hong Kong (China) service access point, set domain name to

     [[XGPush defaultManager] configureClusterDomainName:@""];

    Connection sample

    Call the API for launching TPNS and implement the method in the XGPushDelegate protocol as needed to launch the push service.

    1. Launch TPNS. The AppDelegate sample is as follows:
    @interface AppDelegate () <XGPushDelegate>
    @param AccessID   `AccessID` applied for in the TPNS Console
    @param AccessKey   `AccessKey` applied for in the TPNS Console
    @param delegate   Callback object
    -(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions 
      [[XGPush defaultManager] startXGWithAccessID:<your AccessID> accessKey:<your AccessKey> delegate:self];
    return YES;
    1. In AppDelegate, choose to implement the method in the XGPushDelegate protocol:
    /// Unified callback for message receipt
    /// @param   Notification message object (there are two types: `NSDictionary` and `UNNotification`. For detailed interpretations, please see the sample code)
    /// @note   This callback is the callback for receipt of notification messages in the foreground and of silent messages in all states (the unified click callback should be used for message clicks)
    /// Message type description: if `msgtype` in the `xg` field is 1, it means notification message; if `msgtype` is 2, it means silent message
    - (void)xgPushDidReceiveRemoteNotification:(nonnull id)notification withCompletionHandler:(nullable void (^)(NSUInteger))completionHandler{
     /// code
     /// Unified click callback
    /// @param response   On iOS 10+/macOS 10.14+, it is `UNNotificationResponse`; otherwise, it is `NSDictionary`
    - (void)xgPushDidReceiveNotificationResponse:(nonnull id)response withCompletionHandler:(nonnull void (^)(void))completionHandler {
      /// code

    Notification Service Extension Plugin Integration

    The SDK provides the Service Extension API, which can be called by the client to use the following extensions:

    • Collect precise statistics of message arrivals.
    • Receive images and audiovisual rich media messages.

    For the integration steps, please see Notification Service Extension Use Instructions.


    If this API is not integrated, the "Reached" and "Clicked" in the statistics will be the same.

    Debugging Method

    Enabling debug mode

    Enable debug mode to view detailed TPNS debug information in the end terminal, facilitating fault location.

    Sample code

    // This is to enable debugging
    [[XGPush defaultManager] setEnableDebug:YES];

    Implementing XGPushDelegate protocol

    During debugging, you are recommended to implement this method in the protocol to get detailed debugging information.

    @brief   This registers the callback of the push service
    @param deviceToken   `Device Token` generated by APNs
    @param 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
    @param error   Error message. If `error` is `nil`, the push service has been successfully registered
    @note TPNS SDK1.2.5.3+
    - (void)xgPushDidRegisteredDeviceToken:(nullable NSString *)deviceToken xgToken:(nullable NSString *)xgToken error:(nullable NSError *)error;
    /// Callback for TPNS registration failure
    /// @param error   Error message for registration failure
    /// @note   TPNS SDK1.2.7.1+
    - (void)xgPushDidFailToRegisterDeviceTokenWithError:(nullable NSError *)error {

    Observing logs

    If Xcode console displays a log similar to the one below, the client has properly integrated the SDK.

    [TPNS] Current device token is 9298da5605c3b242261b57****376e409f826c2caf87aa0e6112f944
    [TPNS] Current TPNS token is 00c30e0aeddff1270d8****dc594606dc184  


    Use an XG 36-bit token for pushing to a single target device.

    Unified Message Receipt and Message Click Callback Description

    Unified message receipt callback. This callback will be used when the application receives a notification message in the foreground and receives a silent message in all states (foreground, background, closed).

    - (void)xgPushDidReceiveRemoteNotification:(nonnull id)notification withCompletionHandler:(nullable void (^)(NSUInteger))completionHandler;

    Unified message click callback. This callback method is the notification message click callback in all states of the application (foreground, background, and closed).

    - (void)xgPushDidReceiveNotificationResponse:(nonnull id)response withCompletionHandler:(nonnull void (^)(void))completionHandler;


    • When the application receives a message in the foreground, the unified message receipt callback xgPushDidReceiveRemoteNotification will be triggered.
    • If the unified message receipt callback xgPushDidReceiveRemoteNotification is implemented, please do not implement application:didReceiveRemoteNotification:fetchCompletionHandler again.

    Advanced Configuration (Optional)

    Unregistering XG platform service

    If the application push service is migrated from the XG platform to the TPNS platform, you need to call the API of TPNS SDK( to unregister the device information on the XG platform.


    // TPNS `accessId` (TPNS SDK v2 and v3 supported)
    @property uint32_t freeAccessId;


    • Import the header file XGForFreeVersion.h
    • Call this API before startXGWithAppID:appKey:delegate:. Please see the sample below:
    [XGForFreeVersion defaultForFreeVersion].freeAccessId = 2200262432;
    [[XGPush defaultManager] startXGWithAppID: <#your tpns access ID#>appKey:<#your tpns access key#> delegate:<#your delegate#>];


    If the above configuration is not completed, duplicate messages may appear when pushing on both the XG and TPNS platforms at the same time.

    Suggestions on getting TPNS token

    After you integrate the SDK, you are recommended to use gestures or other methods to display the TPNS token in the application's less commonly used UIs such as About or Feedback. Push through the console and RESTful API requires the TPNS token for token push. Subsequent troubleshooting will also require the TPNS token for problem locating.

    Sample code

    // Get the token generated by TPNS
    [[XGPushTokenManager defaultTokenManager] xgTokenString];

    Was this page helpful?

    Was this page helpful?

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