SDK Integration

Last updated: 2021-07-05 14:36:59

    Use Cases

    This document provides sample codes for integrating with the TPNS SDK and launching the TPNS service.

    SDK composition

    • doc folder: contains the development guide of the TPNS SDK for macOS.
    • demo folder: mainly contains sample projects and the TPNS SDK.

    Integration steps

    Preparing for integration

    1. Log in to the TPNS console and click Product Management on the left side bar.
    2. On the Product Management page, click Add Product.
    3. In the Add Product dialog box, enter the product name and product details, select the product type, and click Confirm to add a new product.
    4. After the product is created, click Configuration Management > Basic Configuration on the left sidebar. You can obtain the AccessID and AccessKEY in the Application Information section.

    Importing the SDK (two methods)

    • Method 1: import using Cocoapods
      Download through CocoaPods:
      pod 'TPNS-macOS' 
      
    • Method 2: Manual import
      Log in to the TPNS console and click SDK Download on the left sidebar to go to the download page. Click Download in the macOS Platform section to download the SDK for macOS.
      1. Go to the demo directory, open the XG-Demo-macOS folder, and add XG_SDK_Cloud_macOS.framework and XGMTACloud_macOS.framework to the project.
      2. Add the following frameworks to Build Phases:
        * XG_SDK_Cloud_macOS.framework
        * XGMTACloud_macOS.framework
         * UserNotifications.framework(10.14+)
        
      3. Click TARGETS > General and select Embed & Sign in the Embed column under the Frameworks,Libraries,and Embedded Content option, as shown in the following figure:

    Project configuration

    1. Enable Push Notifications in the project configuration, as shown in the following figure:
    2. . Add the -ObjC compilation parameter in Build Settings > Other Linker Flags.
    Note:

    If checkTargetOtherLinkFlagForObjc reports an error, it is because -ObjC has not been added in Build Settings > Other Linker Flags.

    Integration sample

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

    1. Launch the TPNS service. The following is a demonstration inAppDelegate:

      - (void)applicationDidFinishLaunching:(NSNotification *)aNotification {
      /// Enable the debug mode and you can view the detailed TPNS debug information on the terminal for troubleshooting.
      //    [[XGPush defaultManager] setEnableDebug:YES];
      [XGPush defaultManager].launchOptions = [[aNotification userInfo] mutableCopy];
      [[XGPush defaultManager] startXGWithAccessID:TPNS_ACCESS_ID accessKey:TPNS_ACCESS_KEY delegate:self];
      if (@available(macOS 10.14, *)) {
          /// For system version higher than v10.14, internal processing will take place with reporting.
      } else {
          UNNotificationResponse *rep = [aNotification userInfo][NSApplicationLaunchUserNotificationKey];
          if (rep) {
              [[XGPush defaultManager] reportXGNotificationInfo:rep.notification.request.content.userInfo];
          }
      }
      }
      
    2. In AppDelegate, choose to implement the method in the XGPushDelegate protocol:

    objective-c
    /// Callback for TPNS registration success
    /// @param deviceToken: device token generated by APNs
    /// @param xgToken: token generated by TPNS. This value is required during message push. TPNS maintains the mapping relationship between this value and the device token generated by APNs.
    /// @param error: error message. If `error` is `nil`, the push service has been successfully registered.
    - (void)xgPushDidRegisteredDeviceToken:(NSString *)deviceToken xgToken:(NSString *)xgToken error:(NSError *)error {
      if (!error) {
          NSLog(@"%s, register success, deviceToken:%@, xgToken:%@", __FUNCTION__, deviceToken, xgToken);
      } else {
          NSLog(@"%s, register failed:%@, deviceToken:%@, xgToken:%@", __FUNCTION__,error.description, deviceToken, xgToken);
      }
    }
    /// Receive callback for notification messages in a unified manner.
    /// @param notification: message object
    /// @param completionHandler: callback completed.
    /// Message type description: if `msgtype` in the `xg` field is `1`, it means notification message; if `msgtype` is `2`, it means silent message.
    /// `notification` message object description: there are two types, `NSDictionary` and `UNNotification`. For detailed interpretations, please see the sample code.
    - (void)xgPushDidReceiveRemoteNotification:(id)notification withCompletionHandler:(void (^)(NSUInteger))completionHandler {
      NSLog(@"[TPNS Demo] receive notification: %@", notification);
    }
    /// Unified click callback
    /// @param response   //`UNNotificationResponse` for iOS 10+ and macOS 10.14+, or `NSDictionary` for earlier versions
    /// Message type description: if `msgtype` in the `xg` field is `1`, it means notification message; if `msgtype` is `9`, it means local notifications.
    - (void)xgPushDidReceiveNotificationResponse:(nonnull id)response withCompletionHandler:(nonnull void (^)(void))completionHandler {
      if ([response isKindOfClass:[UNNotificationResponse class]]) {
          NSLog(@"[TPNS Demo] click notification: %@", ((UNNotificationResponse *)response).notification.request.content.userInfo);
      } else if ([response isKindOfClass:[NSDictionary class]]) {
          NSLog(@"[TPNS Demo] click notification: %@", response);
      }
      completionHandler();
    }
    

    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 2117b45c7e32bcdae2939f******57e420a376bdd44cf6f58613129d2065370
    [TPNS]  Current TPNS token is 0304b8f5d4e*****0af06b37d8b850d95606
    [TPNS]  The server responds correctly, registering device successfully
    

    Suggestions on Integration

    Obtaining a token (optional)

    It is recommended that after you integrate the SDK, you use gestures or other methods to display the token in the app’s less commonly used UI such as About or Feedback. Doing so will facilitate subsequent troubleshooting.

    Sample code

    // Get the token generated by TPNS.
    [[XGPushTokenManager defaultTokenManager] xgTokenString];
    //Obtain the DeviceToken generated by APN
    [[XGPushTokenManager defaultTokenManager] deviceTokenString];