iOS SDK Integration Guide

SDK Instructions

Applicable Version

This article matches the SDK version: after r2.1.5. Check out the latest updates for the latest SDK updates. New version of Push SDK can be used with Xcode 6 and above, and old version of SDK needs to be run with Xcode 5 (1.7.4)

Resource

Package name as JPush-iOS-SDK-{version number}

  • The lib folder: contains the header file JPUSHService.h, the static library files jpush-ios-x.x.x.a, jcore-ios-x.x.x.a, and supporting iOS versions 6.0 and above. (Please note: The simulator does not support APNs)

  • pdf file: Integration Guide

  • demo folder: example

Create an Application

  • Create an application on the management portal of JPush and upload the APNs certificate. If you do not know much about APNs certificates, please refer to:

Setup Guide of iOS Certificate

jpush_ios

  • After the creation is successful, an AppKey is automatically generated to identify the application.

jpush_ios

Configuration Engineering

Import SDK

Option 1: Cocoapods Import

  • Download address through Cocoapods:
    1. pod 'JPush'

  • If you need to install a specific version, use the following method (take the 3.0.2 version as an example):：

    1. pod 'JPush', '3.0.2'

    Option 2: Manually Import

  • Download the latest SDK on Jiguang official website

  • Extract the SDK package and select “Add files to ‘Your project name’…” in Xcode. Add the extracted lib subfolder (including JPUSHService.h, jpush-ios-xxxa, jcore-ios-xxxa) to your project directory

  • Add Framework

    • CFNetwork.framework

    • CoreFoundation.framework

    • CoreTelephony.framework

    • SystemConfiguration.framework

    • CoreGraphics.framework

    • Foundation.framework

    • UIKit.framework

    • Security.framework

    • libz.tbd (the following version of Xcode7 is libz.dylib)

    • AdSupport.framework (for IDFA needs; do not add if you do not use IDFA)

    • UserNotifications.framework (Xcode8 and above)

    • libresolv.tbd (required for JPush 2.2.0 and above, the following version of Xcode7 is libresolv.dylib)

Note: If you integrate JPush 3.0.1 and above, and also integrate other Jiguang SDKs (eg: JMessage 3.0.0 and above)
1. Cocoapods import, suggestions are updated to the latest version online to avoid conflicts caused by inconsistent Jcore version.
2. Manually import, just keep a jcore-ios-x.x.x.a static library file in the project.

Build Settings

If your project needs to support iOS systems less than 7.0, please go to Build Settings to turn off the bitCode option, otherwise it will not compile properly.

  • Set the User Header Search Paths and Library Search Paths under Search Paths. For example, the SDK folder (default as lib) is in the same directory as the project file, then just set both to “$(SRCROOT)/{The name of the folder where the static library is located. }”

Capabilities

If you are using Xcode 8 and above environment to develop, please open the Capabilities->Push Notifications of Application Target, as shown in the figure:

jpush_ios

Allow Xcode7 to Support Http Transfer Method

If you are using version 2.1.9 or above, you do not need to configure this step. If you are using Xcode 7 or later, you need to manually configure the key and value in the plist of the App project to support HTTP transmission:

Option 1: Configure Based on Domain Name

  • Add a Key:NSAppTransportSecurity in the project info.plist, which is a type dictionary.

  • Then add an NSExceptionDomains, which is a type dictionary;

  • Add the required supporting domains to NSExceptionDomains. jpush.cn as Key, is a dictionary type.

  • Two properties need to be set below each domain: NSI IncludeSubdomains, NSExceptionAllowsInsecureHTTPLoads. Both properties are Boolean and the values are YES and YES, respectively.

jpush_ios

Option 2: Global Configuration

  1.   <key>NSAppTransportSecurity</key>
  2.   <dict>
  3.       <key>NSAllowsArbitraryLoads</key>
  4.       <true/>
  5.   </dict>

Add Header Files

Add the following code to the location referring header file in the AppDelegate.m.

  1. // 引入JPush功能所需头文件
  2. #import "JPUSHService.h"
  3. // iOS10注册APNs所需头文件
  4. #ifdef NSFoundationVersionNumber_iOS_9_x_Max
  5. #import <UserNotifications/UserNotifications.h>
  6. #endif
  7. // 如果需要使用idfa功能所需要引入的头文件（可选）
  8. #import <AdSupport/AdSupport.h>

Add Delegate

Add Delegate for AppDelegate.

Reference Code:：

  1. @interface AppDelegate ()<JPUSHRegisterDelegate>
  3. @end

Add Initialization Code

From version 2.1.0, the API class is named JPUSHService and the original APService is no longer used.

Add Initialization APNs Code

Please add the following code to

-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions

  1.   //Required
  2.   //notice: 3.0.0及以后版本注册可以这样写，也可以继续用之前的注册方式
  3.   JPUSHRegisterEntity * entity = [[JPUSHRegisterEntity alloc] init];
  4.   entity.types = JPAuthorizationOptionAlert|JPAuthorizationOptionBadge|JPAuthorizationOptionSound;
  5.   if ([[UIDevice currentDevice].systemVersion floatValue] >= 8.0) {
  6.     // 可以添加自定义categories
  7.     // NSSet<UNNotificationCategory *> *categories for iOS10 or later
  8.     // NSSet<UIUserNotificationCategory *> *categories for iOS8 and iOS9
  9.   }
  10.   [JPUSHService registerForRemoteNotificationConfig:entity delegate:self];

Add Initialization JPush Code

Please add the following code to

-(BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions

  1.   // Optional
  2.   // 获取IDFA
  3.   // 如需使用IDFA功能请添加此代码并在初始化方法的advertisingIdentifier参数中填写对应值
  4.   NSString *advertisingId = [[[ASIdentifierManager sharedManager] advertisingIdentifier] UUIDString];
  6.   // Required
  7.   // init Push
  8.   // notice: 2.1.5版本的SDK新增的注册方法，改成可上报IDFA，如果没有使用IDFA直接传nil
  9.   // 如需继续使用pushConfig.plist文件声明appKey等配置内容，请依旧使用[JPUSHService setupWithOption:launchOptions]方式初始化。
  10.   [JPUSHService setupWithOption:launchOptions appKey:appKey
  11.                         channel:channel
  12.                apsForProduction:isProduction
  13.           advertisingIdentifier:advertisingId];
Some Parameter Descriptions:：

  • appKey

    • Select the application on the Web Portal and click “Settings” to get its appkey value. Make sure the appkey configured in the app is the same as the appkey generated on the portal after the app is created.

  • channel

    • Specify the download channel of the application package. To facilitate the statistics of channels, the specific value is defined by you, such as App Store.

  • apsForProduction

    • Add in Version 1.3.1 to identify the APNs certificate environment used by the current application.

    • 0 (the default value) indicates that the development certificate is used, and 1 indicates that the application is issued by using the production certificate.

    • Note: The value of this field must be the same as the certificate environment of Code Settings configured in Build Settings.

  • advertisingIdentifier

Register APNs Successfully and Report DeviceToken

Please implement this callback method in AppDelegate.m and add the code in the callback method

  1. - (void)application:(UIApplication *)application
  2. didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
  4.   /// Required - 注册 DeviceToken
  5.   [JPUSHService registerDeviceToken:deviceToken];
  6. }

Fail to Register the APNs Interface (Optional)

  2. - (void)application:(UIApplication *)application didFailToRegisterForRemoteNotificationsWithError:(NSError *)error {
  3.   //Optional
  4.   NSLog(@"did Fail To Register For Remote Notifications With Error: %@", error);
  5. }

Add Callback Method of Processing APNs Notification

Please implement this callback method in AppDelegate.m and add the code in the callback method

  1. #pragma mark- JPUSHRegisterDelegate
  3. // iOS 10 Support
  4. - (void)jpushNotificationCenter:(UNUserNotificationCenter *)center willPresentNotification:(UNNotification *)notification withCompletionHandler:(void (^)(NSInteger))completionHandler {
  5.   // Required
  6.   NSDictionary * userInfo = notification.request.content.userInfo;
  7.   if([notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) {
  8.     [JPUSHService handleRemoteNotification:userInfo];
  9.   }
  10.   completionHandler(UNNotificationPresentationOptionAlert); // 需要执行这个方法，选择是否提醒用户，有Badge、Sound、Alert三种类型可以选择设置
  11. }
  13. // iOS 10 Support
  14. - (void)jpushNotificationCenter:(UNUserNotificationCenter *)center didReceiveNotificationResponse:(UNNotificationResponse *)response withCompletionHandler:(void (^)())completionHandler {
  15.   // Required
  16.   NSDictionary * userInfo = response.notification.request.content.userInfo;
  17.   if([response.notification.request.trigger isKindOfClass:[UNPushNotificationTrigger class]]) {
  18.     [JPUSHService handleRemoteNotification:userInfo];
  19.   }
  20.   completionHandler();    // 系统要求执行这个方法
  21. }
  23. - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void (^)(UIBackgroundFetchResult))completionHandler {
  25.   // Required, iOS 7 Support
  26.   [JPUSHService handleRemoteNotification:userInfo];
  27.   completionHandler(UIBackgroundFetchResultNewData);
  28. }
  30. - (void)application:(UIApplication *)application didReceiveRemoteNotification:(NSDictionary *)userInfo {
  32.   // Required,For systems with less than or equal to iOS6
  33.   [JPUSHService handleRemoteNotification:userInfo];
  34. }

Add Callback Method of Handling JPush Custom Message

To use JPush’s custom message functionality, refer to the documentation to implement the callback method of processing a custom message.

Successful Operation

The real machine debugs the project. If the console outputs the following log, it means that you have successfully integrated.

  1. 2016-08-19 17:12:12.745823 219b28[1443:286814]  | JPUSH | I - [JPUSHLogin]
  2. ----- login result -----
  3. uid:5460310207
  4. registrationID:171976fa8a8620a14a4

If you have problems during debugging, please refer to: iOS SDK Debugging Guide

Advanced Features

About IDFA

R2.1.5 adds an interface for uploading IDFA strings

  1.  + (void)setupWithOption:(NSDictionary *)launchingOption
  2.                   appKey:(NSString *)appKey
  3.                  channel:(NSString *)channel
  4.         apsForProduction:(BOOL)isProduction
  5.    advertisingIdentifier:(NSString *)advertisingId;

If you do not use IDFA, you can still use the interface

  1. + (void)setupWithOption:(NSDictionary *)launchingOption
  2.                   appKey:(NSString *)appKey
  3.                  channel:(NSString *)channel
  4.         apsForProduction:(BOOL)isProduction;

Monitoring of JPush SDK Related Event

Developers are advised to add the following types of notifications provided in the API：

extern NSString * const kJPFNetworkIsConnectingNotification; // Joining

extern NSString * const kJPFNetworkDidSetupNotification; // Establish connection

extern NSString * const kJPFNetworkDidCloseNotification; // Close connection

extern NSString * const kJPFNetworkDidRegisterNotification; // Registration succeeded

extern NSString *const kJPFNetworkFailedRegisterNotification; // Registration failed

extern NSString * const kJPFNetworkDidLoginNotification; // Login succeeded

Tips:

The Registration id needs to be added to the method that registers the kJPFNetworkDidLoginNotification notification, or it can call the [registrationIDCompletionHandler:] method and get it through the completionHandler.

extern NSString * const kJPFNetworkDidReceiveMessageNotification; // Receive custom messages (non-APNs)

Among them, the data passed by kJPFNetworkDidReceiveMessageNotification can be obtained through the userInfo method in NSNotification, including title, content, extras information, etc.

Please refer to the documentation: iOS SDK API

Statistics of Notification Delivery

Tips:

The new Notification Service Extension feature in iOS 10 is controlled by the mutable-content field.
If using the Web console, check the mutable-content option in the “optional settings”;
if using the RESTFul API, set the mutable-content field to true.

From the iOS JPush SDK 3.0.7 version, developers can use the Notification Service Extension SDK to report the delivery status of every APNs message.

Instructions:：

  • Introduce two files, jpush-extension-ios-xxx.a and JPushNotificationExtensionService.h, into your Service Extentsion project.

  • Call the [jpushSetAppkey:] method to set your appkey. Please note that the appkey should be the same as the appkey of your Jiguang app.

  • Report your apns message by calling the [jpushReceiveNotificationRequest:] method to complete delivery statistics; display apns in the block callback for this method.

For more specific usage examples, please refer to the demo code included in the compress.

Reference document: iOS SDK API

Technical Support

Email Contact: support@jpush.cn