Connecting the AppMetrica Push SDK

Step 1. Enable the library

The library can work with the following dependency managers:

The library supports static and dynamic frameworks for CocoaPods. To enable the library, add a dependency to the project's Podfile:

  • Static framework

    pod 'YandexMobileMetricaPush', '1.3.0'
    Copied to clipboard
  • Dynamic framework

    pod 'YandexMobileMetricaPush/Dynamic', '1.3.0'
    Copied to clipboard
If you don't use these dependency managers

To enable the library, follow these steps:

  1. Add YandexMobileMetricaPush.framework to the project.
Note. The AppMetrica SDK and AppMetrica Push SDK libraries must both be enabled in one of these ways.

Step 2. Register your app in the Apple Push Notification Service (APNs)

Registration prepares the app to work with push notifications. To send notifications to devices with iOS version 7 and higher, make the following changes to the application code:

// Register for push notifications
if #available(iOS 10.0, *) {
    // iOS 10.0 and above.
    let center = UNUserNotificationCenter.current()
    center.requestAuthorization(options:[.badge, .alert, .sound]) { (granted, error) in
        // Enable or disable features based on authorization.
    }
} else {
    // iOS 8 and iOS 9.
    let settings = UIUserNotificationSettings(types: [.badge, .alert, .sound], categories: nil)
    application.registerUserNotificationSettings(settings)
}
application.registerForRemoteNotifications()
Copied to clipboard

This data is usually passed in the following method:

func application(_ application: UIApplication, didFinishLaunchingWithOptions
                 launchOptions: [UIApplicationLaunchOptionsKey :Any]? = nil) -> Bool

For more details about the methods used, see the documentation at developer.apple.com:

Step 3. Register a device token for your app

To send push notifications using AppMetrica, your app's device token is required. To register it:

Add the following code to AppDelegate:

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data)
{
    // If the AppMetrica SDK library was not initialized before this step,
    // calling the method causes the app to crash.
    YMPYandexMetricaPush.setDeviceTokenFrom(deviceToken)
}
Copied to clipboard

To register the device token and send the APN environments, add the following code:

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data)
{
    // If the AppMetrica SDK library was not initialized before this step,
    // calling the method causes the app to crash.
    #if DEBUG
        let pushEnvironment = YMPYandexMetricaPushEnvironment.development
    #else
        let pushEnvironment = YMPYandexMetricaPushEnvironment.production
    #endif
    YMPYandexMetricaPush.setDeviceTokenFrom(deviceToken, pushEnvironment: pushEnvironment)
}
Copied to clipboard
Attention. AppMetrica allows you to send push notifications to Sandbox APNs. However, push notification processing may not work correctly if versions of the application with different environments were run on the device(development and production). To avoid this issue, you can use a separate test API key for development environment.

Step 4. Configure handling the opening of push notifications.

Configure handling the opening of push notifications:

  1. Add the following code to the appropriate AppDelegate | UIApplicationDelegate methods:

    func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any])
    {
        self.handlePushNotification(userInfo)
    }
    
    func application(_ application: UIApplication, didReceiveRemoteNotification userInfo: [AnyHashable : Any], fetchCompletionHandler completionHandler: @escaping (UIBackgroundFetchResult) -> Void)
    {
        self.handlePushNotification(userInfo)
        completionHandler(.newData)
    }
    
    func handlePushNotification(_ userInfo: [AnyHashable : Any])
    {
        // Track received remote notification.
        // Method [YMMYandexMetrica activateWithApiKey:] should be called before using this method.
        YMPYandexMetricaPush.handleRemoteNotification(userInfo)
    }
    Copied to clipboard
  2. If you also use UISceneDelegate, add the following code to the scene(_:willConnectTo:options:) method:

    func scene(_ scene: UIScene, willConnectTo
               session: UISceneSession, options
               connectionOptions: UIScene.ConnectionOptions) {
         YMPYandexMetricaPush.handleSceneWillConnectToSession(with: connectionOptions)
    }
    Copied to clipboard
Handling push notifications for iOS 9 and below

If you have iOS 9 and lower or you don't use the new notification feature on iOS 10, you'll need to track the receipt of push notifications yourself. To track push notification openings and other actions with them, use the appropriate UIApplicationDelegate methods.

Handling push notifications for iOS 10 and higher

If you have iOS 10 or higher and want to use the new type of push notifications introduced in iOS 10, use the YMPUserNotificationCenterDelegate delegate. It handles the receipt of push notifications automatically when they're opened.

Make the following changes to the code:

import UserNotifications

// In the "func application(_ application: UIApplication, didFinishLaunchingWithOptions 
//                          launchOptions: [UIApplicationLaunchOptionsKey : Any]? = nil) -> Bool" method:
if #available(iOS 10.0, *) {
    let delegate = YMPYandexMetricaPush.userNotificationCenterDelegate()
    UNUserNotificationCenter.current().delegate = delegate
}
Copied to clipboard

To track push notification openings and other actions with them, create your own delegate named UNUserNotificationCenterDelegate and add it to nextDelegate:

YMPYandexMetricaPush.userNotificationCenterDelegate().nextDelegate = yourDelegate
Copied to clipboard

After that, you can use the appropriate methods of your delegate.

Step 5. (Optional) Enable push tokens update

The APNS service can withdraw the push token of the device, for example, if the user did not launch the application for a long time. AppMetrica stores push tokens on the server and can not send a push notification to a device with an obsolete token.

To automatically collect current push token go to the application settings in the AppMetrica interface and enable the Update tokens with a Silent Push notification option in the Push Notifications tab.

Step 6. (Optional) Configure uploading attached files

Note.

The functionality is not available in the web interface of push campaigns.

You can configure uploading attached files in push notifications:
  1. Configure uploading attached files in push notifications by calling the downloadAttachmentsForNotificationRequest method in the Push SDK. See an example of integration in the article Uploading attached files.
  2. Add attachments (the attachments parameter) using the Sending push messages operation in the Push API.

Sending additional information

You can send additional information with the push notification if necessary. This data is specified in the AppMetrica web interface when configuring the push campaign. To get this information, use the following method:

let userData = YMPYandexMetricaPush.userData(forNotification: userInfo)
Copied to clipboard

where userInfo contains information about the push notification.

Defining the recipient of a notification

AppMetrica allows you to detect “own” push notifications, if several Push SDKs were built into the application.

To detect, if the AppMetrica is the recipient of a notification, use the following method:

let isRelatedToAppMetricaSDK = YMPYandexMetricaPush.isNotificationRelated(toSDK: userInfo)
Copied to clipboard

If you didn't find the answer you were looking for, you can use the feedback form to submit your question. Please describe the problem in as much detail as possible. Attach a screenshot if possible.