Campaigns

Simple Push

Note: Simple Push Campaigns are served by Push Notifications. Before you can start using this feature, you have to configure it. Check the Push Notifications section for more details.

If an app was not active (was closed or running in the background) and a campaign comes in, a push notification appears in the notification center. When a user clicks the notification, they are taken to the application and a simple push is presented.

If an app is active, the simple push is presented right away.

Incoming push payload

{
  "aps": {
    "alert": {
      "title": "Your Simple Push Campaign title",
      "body": "Your Simple Push Campaign body"
    },
  "sound": "default",
  "badge": "1",
  "category": "CATEGORY"
  },
  "issuer": "Synerise",
  "message-type": "dynamic-content",
  "content-type": "simple-push",
  "content": {
    "campaign": {
      "variant_id": 1,
      "hash_id": "HASH",
      "type": "CAMPAIGN_TYPE",
      "title": "CAMPAIGN_TITLE"
    },
  "notification": {
    "action": {
      "type": "OPEN_APP",
    }
  },
  "buttons": [
    {
      "identifier": "button1",
      "text": "OPEN_URL",
      "action": {
        "type": "OPEN_URL",
        "item": "www.example.com"
      }
    },
    {
      "identifier": "button2",
      "text": "DEEP_LINKING",
      "action": {
        "type": "DEEP_LINKING",
        "item": "syne://product?sku=1"
      }
    },
    {
      "identifier": "button3",
      "text": "OPEN_APP",
      "action": {
        "type": "OPEN_APP"
      }
    }
  ]
  }
}

Configure Rich Media

At this point, Simple Push Campaign supports two types of Rich Media extensions: Single Media and Image Carousel.

To add this feature in your Simple Push Campaigns, you have to:

  1. Configure App Group that identifies the group used by applications and extensions belongs to.
    More information about configuring App Groups - Apple Developer - App Groups

  2. Add Notification Content Extension in your iOS project - separately for each type of our Rich Media extensions.
    Extensions must inherit from our classes:

  3. Configure your application and the SDK

Synerise SDK does most of the work needed and provides classes for Notification Content Extensions. When you create an extension, you just have to make it inherited from Synerise SDK suitable class.

import UIKit
import UserNotifications
import UserNotificationsUI
import SyneriseSDK

class NotificationViewController: SingleMediaContentExtensionViewController, UNNotificationContentExtension {

    func didReceive(_ notification: UNNotification) {
        Synerise.settings.notifications.appGroupIdentifier = "YOUR_APP_GROUP_IDENTIFIER"
        setSyneriseNotification(notification)
    }

    func didReceive(_ response: UNNotificationResponse, completionHandler completion: @escaping (UNNotificationContentExtensionResponseOption) -> Void) {
        setSyneriseNotificationResponse(response, completionHandler: completion)
    }
}
Note: You have to remember about correct configuration in your extension *.plist file. See our code in Sample Swift App.

Once you have it configured you have to pass your app group identifier to the SDK (Setup App Group Identifier) and add custom categories in your application.

Synerise.settings.notifications.appGroupIdentifier = "YOUR_APP_GROUP_IDENTIFIER"

let singleMediaCategory = UNNotificationCategory(identifier: SNRSingleMediaContentExtensionViewControllerCategoryIdentifier, actions: [], intentIdentifiers: [], options: [])

let carouselPrevious = UNNotificationAction(identifier: SNRCarouselContentExtensionViewControllerPreviousItemIdentifier, title: "Previous", options: [])
let carouselAction = UNNotificationAction(identifier: SNRCarouselContentExtensionViewControllerChooseItemIdentifier, title: "Go!", options: UNNotificationActionOptions.foreground)

let carouselNext = UNNotificationAction(identifier: SNRCarouselContentExtensionViewControllerNextItemIdentifier, title: "Next", options: [])

let carouselCategory = UNNotificationCategory(identifier: SNRCarouselContentExtensionViewControllerCategoryIdentifier, actions: [carouselPrevious, carouselAction, carouselNext], intentIdentifiers: [], options: [])

UNUserNotificationCenter.current().setNotificationCategories([singleMediaCategory, carouselCategory])

You have to set notifications categories with right identifiers. You must take it from Synerise SDK constants to make these working. But you can feel at free in naming buttons.

Note: Our Sample App shows configuration and extensions, you can check it on our GitHub.

Silent Push

Note: Silent Push Campaign is served by Push Notifications. Before you can start using this feature, you have to configure it. Check Push Notifications section for more details.

Silent Push is just Silent Push Notification that you can send from app.synerise.com.


Note: Banner Campaign is served by Silent Push Notifications. Before you can start using this feature, you have to configure it. Check Push Notifications section for more details.

Banners cover the entire screen and appear immediately.

It is not always suitable for you to show banners which may come. The application may be in a state you do not want banner cannot cover the user’s screen.

Fortunately, you can control incoming banners by implementing an optional delegate SNRInjectorBannerDelegate

Incoming push payload

Banners can have different layouts, currently:

  • COLOR AS BACKGROUND
  • IMAGE AS BACKGROUND
  • IMAGE WITH TEXT ATOP
  • IMAGE WITH TEXT BELOW

Example payload of banner with COLOR AS BACKGROUND layout:

{
  "aps": {
    "content-available": 1
  },
  "issuer": "Synerise",
  "message-type": "dynamic-content",
  "content-type": "template-banner",
  "content": {
    "campaign": {
      "variant_id": 1,
      "hash_id": "id1",
      "type": "CAMPAIGN_TYPE",
      "title": "CAMPAIGN_TITLE"
    },
    "page": {
      "index": 0,
      "type": "color_as_background",
      "background": {
        "color": "#ffffff",
        "alpha": 1
      },
      "header": {
        "text": "\n{ guard let }",
        "color": "#000000",
        "alpha": 1,
        "size": 65
      },
      "description": {
        "text": "\n\n#ios\n#development\n#videos\n#blog",
        "color": "#555555",
        "alpha": 1,
        "size": 30
      },
      "button": {
        "is_enabled": false,
        "color": "#f9fafb",
        "text": "URL: www.example.com",
        "text_color": "#384350",
        "corner_radius": 5
      },
      "close_button": {
        "is_enabled": true,
        "alignment": "right"
      },
      "action": {
        "type": "OPEN_URL",
        "item": "www.example.com"
      }
    }
  }
}

Triggers

In order to show a banner immediately after a certain event occurred, you can send your banners from app.synerise.com with a TRIGGER value.

Banners are fetched during the SDK initialization and when the application works, these banners are being searched for eventual campaign triggers.

Additionaly, you can deal with banners by yourself.

You can keep banner data from:

  • Injector.fetchBanners(success:failure:) - fetch available banners (the SDK will refresh cache).
  • Injector.getBanners() - get available banners from the SDK cache.

Next, you can call Injector.showBanner(_:) method to show a banner immediately. In this case, the delegate method snr_shouldBannerAppear(bannerDictionary:) will not be called.


Mandatory Upgrade

Mandatory Upgrade is just Banner but it haven’t close button. The only one ption that the user can do is redirecting to website or AppStore and installing new version of the application.


Walkthrough

Walkthrough is scrollable set of pages that cover the entire screen.

Walkthrough’s pages can have different layouts, the same like in banners:

  • COLOR AS BACKGROUND
  • IMAGE AS BACKGROUND
  • IMAGE WITH TEXT ATOP
  • IMAGE WITH TEXT BELOW

Configure Walkthrough

First of all, you are able to specify Walkthrough behavior in the SDK Settings - Enable / Disable automatic starting mobile campaigns.

AUTOMATIC:

Automatic behavior fetches Walkthrough right away. Note, that Walkthrough will be presented atop of your current View Controller after application launched.

MANUAL:

When you control Walkthrough manually, you can do it when you want and where you want.

To control this behavior please fetch your Walkthrough manually with Injector.getWalkthrough(). Also, it must be called after setup SNRInjectorWalkthroughDelegate.

You can check if Walkthrough is already loaded with Injector.isWalkthroughLoaded() method, which returns true if Walkthrough is already loaded.

Moreover, there is an enhanced method to check if Walkthrough is loaded. Injector.isLoadedWalkthroughUnique() verifies whether loaded Walkthrough is different than previously presented. Every time any Walkthrough is presented its id is cached locally, therefore you can control your flow more precisely. In summary, the method will return true if loaded Walkthrough is different than previously presented, false otherwise or if Walkthrough is not loaded.

Finally, Injector.showWalkthrough() shows Walkthrough if loaded. This method may be called wherever in your application as many times you want. It also returns true if Walkthrough was loaded, false otherwise.

When you choose to load and present Walkthrough manually, you may be interested in a sample implementation of SNRInjectorWalkthroughDelegate:

// MARK: - InjectorWalkthroughDelegate

// this method will be called when Walkthrough is loaded
func snr_walkthroughDidLoad() {
  if Injector.isWalkthroughLoaded() {
    if Injector.isLoadedWalkthroughUnique() {
      Injector.showWalkthrough()
    }
  }
}

// this method will be called when an error occurs while loading Walkthrough
func snr_walkthroughLoadingError(error: Error) {
  print(error.localizedDescription)
}

// this method will be called when Walkthrough appeared
func snr_walkthroughDidAppear() {
  //...
}

// this method will be called when Walkthrough disappeared
func snr_walkthroughDidDisappear() {
  //...
}

Handling actions from campaigns

Note: SNRSyneriseDelegate defines optional methods to handling actions from the whole SDK but it can be used for handling campaign interactions. Description below is just implementation these methods.

Synerise SDK handles two main actions that user may invoke:

  • OPEN_URL
  • DEEPLINKING

Important - If you don’t configure custom action for OPEN_URL, the SDK just run default browser with requested URL address.

In extended methods for handling UR and DEEP_LINKING, there are parameters:

SNRSyneriseActivity

It’s enum type that defines kind of activity from action that was sent.

SNRSyneriseActivityCompletionHandler

It’s block/closure that defines should activity hide or not and what code should be invoked after.

Example implementation of OPEN_URL action

// MARK: - SyneriseDelegate

func snr_handledAction(url: URL, activity: SyneriseActivity, completionHandler: SyneriseActivityCompletionHandler) {
  if activity == .walkthrough {
    completionHandler(.none, {
      if UIApplication.shared.canOpenURL(url) {
        if #available(iOS 10, *) {
            UIApplication.shared.open(url, options:[:], completionHandler:nil)
        } else {
            UIApplication.shared.openURL(url)
        }
      }
    })

    return
  }

  if activity == .banner || activity == .simplePush {
    completionHandler(.hide, {
      //...
    })

    return
  }
}

Example implementation of DEEP_LINKING action

// MARK: - SyneriseDelegate

func snr_handledAction(deepLink: String, activity: SyneriseActivity, completionHandler: SyneriseActivityCompletionHandler) {
  if activity == .walkthrough {
    completionHandler(.none, {
      goToHelpWithId(deepLink)
    })

    return
  }

  if activity == .banner {
    completionHandler(.hide, {
      goToPromotionFromDeepLink(deepLink)
    })

    return
  }

  if activity == .simplePush {
    completionHandler(.hide, {
      goToMessageWithId(deepLink)
    })

    return
  }
}

Other features

Blocking Campaigns

If you don’t want to show any of Synerise campaigns in some place your application or if there are View Controllers that should never to be covered by Synerise activity (for example banner), you can block it easily.

The only you need is adding SyneriseActivityNotAllowed protocol in your View Controller declaration.

For example:

class SampleViewController: UIViewController, SyneriseActivityNotAllowed {

}
Note: When View Controller implements that protocol and Synerise tries to run activity, it will be skipped.

Own implementation for campaigns

You can also react to Synerise push notifications by yourself and that is why we would like to share our Synerise Simple Push and Synerise Banner payload (see corresponding sections above).

You may need to know whether incoming push message comes from Synerise.

Synerise.isSyneriseNotification(_:) - checks whether provided push data comes from Synerise. It is validated by checking if incoming push contains “issuer” key with “Synerise” value.

Example:

func userNotificationCenter(_ center: UNUserNotificationCenter, willPresent notification: UNNotification, withCompletionHandler completionHandler: @escaping (UNNotificationPresentationOptions) -> Void) {
  let userInfo = notification.request.content.userInfo
  let isSyneriseNotification: Bool = Synerise.isSyneriseNotification(userInfo)
  if isSyneriseNotification {
    // default implementation by Synerise SDK
    // Synerise.handleNotification(userInfo)
    // or
    // your own implementation
    completionHandler(UNNotificationPresentationOptions.init(rawValue: 0))
  } else {
    //…
  }
}

Get Campaign Push Notifications information

You can get configured pushes on app.synerise.com by Injector.getPushes(success:failure:) method.

It contains data from:

  • Simple Push Campaign
  • Silent Push Campaign
😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.