PWEngagement Class Reference

Inherits from NSObject
Declared in PWEngagement.h

Overview

The mobile engagement framework is a location and notification based system.

The recommended way to start mobile engagement in your application is to place a call to +startWithmaasAppId:accessKey:signatureKey:encryptionKey:completion: in your -application:didFinishLaunchingWithOptions: method.

This delay defaults to 1 second in order to generally give the application time to fully finish launching.

The framework needs you to forward the following methods from your application delegate:

  • ‘didFinishLaunchingWithOptions:withCompletionHandler:’
  • ‘didRegisterForRemoteNotificationsWithDeviceToken:withNotificationHandler:’
  • ‘didFailToRegisterForRemoteNotificationsWithError:withNotificationHandler:’
  • ‘didReceiveRemoteNotification:withNotificationHandler:’

You can optionally add a delegate to be informed about errors while initializing the mobile engagement service and to control the display of local notifications to the user.

+ startWithMaasAppId:accessKey:signatureKey:completion:

Starts the mobile engagement service with environment.

+ (void)startWithMaasAppId:(NSString *)maasAppId accessKey:(NSString *)accessKey signatureKey:(NSString *)signatureKey completion:(void ( ^ ) ( NSError *error ))completion

Parameters

maasAppId

You can find your Application ID in the MaaS portal.
accessKey

A unique key that identifies the client making the request. You can find your Access Key in the MaaS portal.
signatureKey

A unique key that is used to sign requests. The signature is used to both check request authorization as well as data integrity. You can find your Signature Key in the MaaS portal.
completion

A block that notify mobile engagement service is successfully started or failed to start with reason. - param1 error It’s nil when it’s started successfully, or an error object containing information about a problem that indicates mobile engagement service failed to start.

Declared In

PWEngagement.h

+ stopWithCompletion:

Stop mobile engagement service.

+ (void)stopWithCompletion:(void ( ^ ) ( NSError *error ))completion

Parameters

completion

A block that notify mobile engagement service is successfully stopped or failed to stop with reason.

  • error It’s nil when it’s stopped successfully, or an error object containing information about a problem that indicates mobile engagement service failed to stop.

Declared In

PWEngagement.h

+ geozones

All the available PWMEGeozone list.

+ (NSArray<PWMEGeozone*> *)geozones

Declared In

PWEngagement.h

+ deviceId

Return the device identifier which the mobile engagement service uses.

+ (NSString *)deviceId

Declared In

PWEngagement.h

+ version

Return the current SDK version of mobile engagement.

+ (NSString *)version

Declared In

PWEngagement.h

+ serviceName

The name of the mobile engagement service.

+ (NSString *)serviceName

Declared In

PWEngagement.h

+ setErrorHandler:

Set the block to handle the error when it occurs.

+ (void)setErrorHandler:(void ( ^ ) ( NSError *error ))handler

Parameters

handler

A block that caused mobile engagement service failed.

  • error An error object containing information about a problem that indicates mobile engagement service failed if the results are retrieved successfully.

Declared In

PWEngagement.h

+ setLocalNotificationHandler:

Set the block to handle the local notification which is about to display.

+ (void)setLocalNotificationHandler:(BOOL ( ^ ) ( PWMELocalNotification *notification ))handler

Parameters

handler

A block that notifies the local notification is about to display, you can control the local notification display and customize the display content.

Discussion

The local notification will be displayed if the block returns YES, otherwise, it will not be displayed.

Declared In

PWEngagement.h

+ didFinishLaunchingWithOptions:withCompletionHandler:

Lets the mobile engagement service know that launch process is almost done and the app is almost ready to run.(APNs).

+ (void)didFinishLaunchingWithOptions:(NSDictionary *)launchOptions withCompletionHandler:(BOOL ( ^ ) ( PWMELocalNotification *notification ))completionHandler

Parameters

launchOptions

A dictionary indicating the reason the app was launched (if any). The contents of this dictionary may be empty in situations where the user launched the app directly. For information about the possible keys in this dictionary and how to handle them, see Launch Options Keys.
completionHandler

A block that tells if user opens the app by tapping a notification.

  • notification The notification object if user open the app by tapping a notification from notification tray, otherwise, it’s nil.

Discussion

The message deep linking could be fired from the completionHandler block. And if returns YES in the block, it will prompt an alert tells user how to enable push notification setting when it’s disabled, and the prompted message could be configured in localized string file with key RemindOfEnablePushNotificationSettings.

Declared In

PWEngagement.h

+ didRegisterForRemoteNotificationsWithDeviceToken:

Lets the mobile engagement service know that the app successfully registered with Apple Push Notification service (APNs).

+ (void)didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken

Parameters

deviceToken

A token that identifies the device to APNs. The token is an opaque data type because that is the form that the provider needs to submit to the APNs servers when it sends a notification to a device. The APNs servers require a binary format for performance reasons. The size of a device token is 32 bytes. Note that the device token is different from the uniqueIdentifier property of UIDevice because, for security and privacy reasons, it must change when the device is wiped.

Declared In

PWEngagement.h

+ didFailToRegisterForRemoteNotificationsWithError:

Lets the mobile engagement service know that the Apple Push Notification service cannot successfully complete the registration process.

+ (void)didFailToRegisterForRemoteNotificationsWithError:(NSError *)error

Parameters

error

An NSError object that encapsulates information why registration did not succeed. The app can choose to display this information to the user.

Declared In

PWEngagement.h

+ didReceiveLocalNotification:withNotificationHandler:

Lets the mobile engagement service know that the app receives a local notification, so that it can process it internally.

+ (void)didReceiveLocalNotification:(UILocalNotification *)notification withNotificationHandler:(void ( ^ ) ( PWMELocalNotification *notification ))notificationHandler

Parameters

notification

A UILocalNotification object.
notificationHandler

A block that tells the notification with message which was received. - notification The notification object which was received.

Discussion

The message deep linking could be fired from the completion block. This method is deprecated since iOS 10, please use didReceiveNotification:withNotificationHandler: instead.

Declared In

PWEngagement.h

+ didReceiveRemoteNotification:withNotificationHandler:

Lets the mobile engagement service know that the app receives a remote notification, so that it can process it internally.

+ (void)didReceiveRemoteNotification:(NSDictionary *)userInfo withNotificationHandler:(void ( ^ ) ( PWMELocalNotification *notification ))notificationHandler

Parameters

userInfo

A dictionary that contains information related to the remote notification, potentially including a badge number for the app icon, an alert sound, an alert message to display to the user, a notification identifier, and custom data. The provider originates it as a JSON-defined dictionary that iOS converts to an NSDictionary object; the dictionary may contain only property-list objects plus NSNull.
notificationHandler

A block that tells the notification with message which was received.

  • notification The notification object which was received.

Discussion

The message deep linking could be fired from the notificationHandler block. This method is deprecated since iOS 10, please use didReceiveNotification:withNotificationHandler: instead.

Declared In

PWEngagement.h

+ didReceiveRemoteNotification:fetchCompletionHandler:withNotificationHandler:

Lets the mobile engagement service know that the app receives a remote notification, so that it can process it internally.

+ (void)didReceiveRemoteNotification:(NSDictionary *)userInfo fetchCompletionHandler:(void ( ^ ) ( UIBackgroundFetchResult ))completionHandler withNotificationHandler:(void ( ^ ) ( PWMELocalNotification *notification ))notificationHandler

Parameters

userInfo

A dictionary that contains information related to the remote notification, potentially including a badge number for the app icon, an alert sound, an alert message to display to the user, a notification identifier, and custom data. The provider originates it as a JSON-defined dictionary that iOS converts to an NSDictionary object; the dictionary may contain only property-list objects plus NSNull.
completionHandler

The block to execute when the download operation is complete. When calling this block, pass in the fetch result value that best describes the results of your download operation. You must call this handler and should do so as soon as possible. For a list of possible values, see the UIBackgroundFetchResult type.

  • userInfo A dictionary that contains information related to the remote notification, potentially including a badge number for the app icon, an alert sound, an alert message to display to the user, a notification identifier, and custom data. The provider originates it as a JSON-defined dictionary that iOS converts to an NSDictionary object; the dictionary may contain only property-list objects plus NSNull.
notificationHandler

A block that tells the notification with message which was received.

  • notification: The notification object which was received.

Discussion

The message deep linking could be fired from the notificationHandler block. This method is deprecated since iOS 10, please use didReceiveNotification:withNotificationHandler: instead.

Declared In

PWEngagement.h

+ didReceiveNotification:withCompletion:

Lets the mobile engagement service know that the app receives a notification, so that it can process it internally, typically when you receive a notification in application:didReceiveRemoteNotification:fetchCompletionHandler:, userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler: and userNotificationCenter:willPresentNotification:withCompletionHandler:.

+ (void)didReceiveNotification:(NSDictionary *)userInfo withCompletion:(void ( ^ ) ( Message *message , NSError *error ))completion

Parameters

userInfo

A dictionary that contains information related to the remote notification, potentially including a badge number for the app icon, an alert sound, an alert message to display to the user, a notification identifier, and custom data. The provider originates it as a JSON-defined dictionary that iOS converts to an NSDictionary object; the dictionary may contain only property-list objects plus NSNull.
completion

A block that returns the notification with the received message or error.

Discussion

The message deep linking could be fired from the notificationHandler block.

Declared In

PWEngagement.h

+ setStaticIdentifier:completion:

Set the static identifier to be registered with the current device.

+ (void)setStaticIdentifier:(NSString *)staticIdentifier completion:(void ( ^ ) ( NSError *error ))completion

Parameters

staticIdentifier

The identifier that will be associated with the current device identifier.
completion

The block that notifies the user when static identifier registration is complete, and whether or not there was an error on the registration request.

Discussion

This registers the selected static identifier with the device identifier.

Declared In

PWEngagement.h

+ startWithMaasAppId:accessKey:signatureKey:encryptionKey:completion:

This method has been deprecated. Starts the mobile engagement service with environment.

+ (void)startWithMaasAppId:(NSString *)maasAppId accessKey:(NSString *)accessKey signatureKey:(NSString *)signatureKey encryptionKey:(NSString *)encryptionKey completion:(void ( ^ ) ( NSError *error ))completion

Parameters

maasAppId

You can find your Application ID in the MaaS portal.
accessKey

A unique key that identifies the client making the request. You can find your Access Key in the MaaS portal.
signatureKey

A unique key that is used to sign requests. The signature is used to both check request authorization as well as data integrity. You can find your Signature Key in the MaaS portal.
encryptionKey

The key used to encrypt and decrypt data that is exchanged between the client and the server. You can find your Encryption Key in the MaaS portal.
completion

A block that notify mobile engagement service is successfully started or failed to start with reason. - param1 error It’s nil when it’s started successfully, or an error object containing information about a problem that indicates mobile engagement service failed to start.

Declared In

PWEngagement.h