Campaigns

Basics

Campaigns types

Synerise campaigns are served in two ways:

  • By Push Notifications:

    • Simple Push
    • Simple Push with Rich Media
    • Silent Push Notification
    • Template Banner
    • Mandatory Upgrade

  • By Synerise backend:

    • Walkthrough
Note: Most of Synerise campaigns are served by Push Notifications. To configure Push Notifications, read more in the Push Notifications section.

Synerise Push Notification structure

Each notification follows this basic structure:

{
  "aps": {
    ...
  },    
  "issuer": "Synerise",
  "message-type": "dynamic-content",
  "content-type": "template-banner",
  "content": {

  }
}
  • issuer - in Synerise notifications, the issuer is always Synerise.
  • message-type - specifies if the content is static or dynamic.
  • content-type - specifies the type of content in the payload.
  • content - the actual content (for example, in HTML).

Methods such as Synerise.isNotificationSimplePush(_:) let you check if the incoming content is of the expected type.

Simple Push

If an app was not active (was closed or running in the background) and a campaign is received, a push notification appears in the notification center. When a customer 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

If you want to handle notifications with your own methods, remember to change the issuer field. If issuer is set to “Synerise”, the payload is always handled by the Synerise SDK.

{
  "aps": {
    "alert": {
      "title": "Complete your purchase",
      "body": "Your basket contains Road Bike RS-500 with a discount for \"New Users\". Come and complete your purchase!"
    },
    "sound": "default",
    "category": "[YOUR CATEGORY]",
    "mutable-content": 1
  },
  "issuer": "Synerise",
  "message-type": "dynamic-content",
  "content-type": "simple-push",
  "content": {
    "campaign": {
      "variant_id": 3175648,
      "hash_id": "196211cc-af48-4064-8860-aad986449322",
      "type": "Simple Push",
      "title": "Simple Push campaign for docs"
    },
    "notification": {
      "action": {
        "type": "OPEN_APP"
      }
    },
    "buttons": [{
      "identifier": "check",
      "text": "Check",
      "action": {
        "type": "OPEN_URL",
        "item": "http://www.synerise.com"
      }
    },
    {
      "identifier": "view_similiar",
      "text": "View similiar",
      "action": {
        "type": "OPEN_URL",
        "item": "http://www.synerise.com"
      }
    }]
  }
}

Example

A Simple Push campaign with main action and two clickable buttons connected to actions. All user interactions are tracked with the use of Synerise iOS SDK.

Simple Push campaign
Simple Push campaign presented on iOS 14
Note: The look of your push notifications may vary depending on iOS versions.

Simple Push (with Rich Media)

Note: Add support for Rich Media Push Notifications in your application. See Rich Media in Push Notifications section.

Simple Push campaign supports two types of Rich Media extensions:

  • Single Media
  • Image Carousel

Simple Push - Single Media

Incoming push payload

{
  "aps": {
    "alert": {
      "title": "Complete your purchase",
      "body": "Your basket contains Road Bike RS-500 with a discount for \"New Users\". Come and complete your purchase!"
    },
    "sound": "default",
    "category": "synerise.notifications.category.single-media",
    "mutable-content": 1
  },
  "issuer": "Synerise",
  "message-type": "dynamic-content",
  "content-type": "simple-push",
  "content": {
    "campaign": {
      "variant_id": 3175648,
      "hash_id": "196211cc-af48-4064-8860-aad986449322",
      "type": "Simple Push",
      "title": "Simple Push campaign for docs"
    },
    "notification": {
      "action": {
        "type": "OPEN_APP"
      }
    },
    "buttons": [{
      "identifier": "check",
      "text": "Check",
      "action": {
        "type": "OPEN_URL",
        "item": "http://www.synerise.com"
      }
    },
    {
      "identifier": "view_similiar",
      "text": "View similiar",
      "action": {
        "type": "OPEN_URL",
        "item": "http://www.synerise.com"
      }
    }],
    "rich-media": {
      "type": "single-image",
      "single-image": {
        "image": "https://upload.snrcdn.net/f2afa4d4d7af216196047d1f7f0613f22a50a8c8/default/origin/7eba69de2d4dab3a9388b9d72abd91eb.png"
      }
    }
  }
}

Example

A Simple Push campaign with a main action, single image, and two clickable buttons connected to actions. All user interactions are tracked with the use of Synerise iOS SDK.

Simple Push campaign
Simple Push campaign presented on iOS 14
Note: The look of your push notifications may vary depending on iOS version.

Simple Push - Image Carousel

Incoming push payload

{
    "aps":
    {
        "alert":
        {
            "title": "Complete your purchase",
            "body": "Your basket contains Road Bike RS-500 with a discount for \"New Users\". Come and complete your purchase!"
        },
        "sound": "default",
        "badge": "5",
        "category": "synerise.notifications.category.carousel"
    },
    "issuer": "Synerise",
    "message-type": "dynamic-content",
    "content-type": "simple-push",
    "content":
    {
        "campaign":
        {
            "variant_id": 3175648,
            "hash_id": "196211cc-af48-4064-8860-aad986449322",
            "type": "Simple Push",
            "title": "Simple Push campaign for docs"
        },
        "notification":
        {
            "action":
            {
                "type": "OPEN_URL",
                "item": "https://www.synerise.com"
            }
        },
        "rich-media":
        {
            "type": "carousel",
            "carousel":
            {
                "orientation": "PORTRAIT",
                "items":
                [
                    {
                        "caption": "Check!",
                        "subcaption": "Road Bike RS-500",
                        "image": "https://upload.snrcdn.net/f2afa4d4d7af216196047d1f7f0613f22a50a8c8/default/origin/7eba69de2d4dab3a9388b9d72abd91eb.png",
                        "url": "https://www.synerise.com"
                    },
                    {
                        "caption": "Check!",
                        "subcaption": "Road Bike RS-500",
                        "image": "https://upload.snrcdn.net/f2afa4d4d7af216196047d1f7f0613f22a50a8c8/default/origin/7eba69de2d4dab3a9388b9d72abd91eb.png",
                        "url": "https://www.synerise.com"
                    }
                ]
            }
        }
    }
}

Example

A Simple Push campaign with a main action and carousel of images with connected actions. All user interactions are tracked with the use of Synerise iOS SDK.

Note: The look of your push notifications may vary depending on iOS versions.
Simple Push campaign
Simple Push campaign presented on iOS 14

Silent Push

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

Banners cover the entire screen and appear immediately.

It is not always suitable for you to display every incoming banner. The application may be in a state where you don’t want to interrupt the customer.

You can control incoming banners by implementing an optional delegate InjectorBannerDelegate

Incoming push payload

Banners can have the following layouts:

  • color_as_background
  • image_as_background
  • image_with_text_atop
  • image_with_text_below

Example payload of a banner with the color as background layout: 

{
  "aps": {
    "content-available": 1
  },
  "issuer": "Synerise",
  "message-type": "dynamic-content",
  "content-type": "template-banner",
  "content": {
    "page": {
      "index": 0,
      "type": "image_as_background",
      "image": {
        "url": "https://upload.snrcdn.net/f2afa4d4d7af216196047d1f7f0613f22a50a8c8/default/origin/e41a376fc3fa913cd316960bfce05171.png"
      },
      "background": {
        "color": "#e9edee",
        "alpha": 1
      },
      "button": {
        "is_enabled": false,
        "text": "CTA",
        "text_color": "#384350",
        "color": "#dbe0e3",
        "corner_radius": 4
      },
      "close_button": {
        "is_enabled": true,
        "alignment": "RIGHT"
      },
      "action": {
        "type": "OPEN_APP"
      }
    },
    "campaign": {
      "hash_id": "30a09e7f-4c7f-47ba-bed9-7d9bc451e221",
      "variant_id": 3175871,
      "type": "Mobile push",
      "title": "Banner campaign for docs"
    },
    "auto_disappear": {
      "is_enabled": false,
      "timeout": 4
    }
  }
}

Example

This is a background-type clickable banner with a main action.

Banner campaign
Banner campaign

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 while the application is running, these banners are searched for campaign triggers.

Additionally, you can process banners by yourself:

  1. Get banner data in one of the following ways:
    • Injector.fetchBanners(success:failure:) - fetch available banners (the SDK refreshes the cache).
    • Injector.getBanners() - get available banners from the SDK cache.
  2. Call the banner immediately by calling the Injector.showBanner(_:) method.
    In this case, the delegate method snr_shouldBannerAppear(bannerDictionary:) is not called.

Delegate implementation

Here is a sample implementation of InjectorBannerDelegate:

// MARK: - InjectorBannerDelegate

// This method is called after a banner is loaded and Synerise SDK asks for permission to show it.
func snr_shouldBannerAppear(bannerDictionary: [AnyHashable: Any]) -> Bool {
  return true
}

// This method is called after a banner appears.
func snr_bannerDidAppear() {
  //...
}

// This method is called after a banner disappears.
func snr_bannerDidDisappear() {
  //...
}

Mandatory Upgrade

Mandatory upgrade is a banner that does not have a close button. The only thing a customer can do is being redirected to a website or the AppStore and installing the new version of the application.

Walkthrough

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

The pages of the walkthrough can have different layouts, same as banner types:

  • color_as_background
  • image_as_background
  • image_with_text_atop
  • image_with_text_below

You can specify Walkthrough behavior in the SDK Settings - Enable/Disable Automatic Mode.

Automatic Mode

Automatic behavior fetches the Walkthrough right away. The Walkthrough will be presented atop of your current View Controller after the application launches.

Manual Mode

When you control the Walkthrough manually, you can show it anywhere at any time.

To control this behavior, fetch your Walkthrough manually with Injector.getWalkthrough(). It must be called after setting up InjectorWalkthroughDelegate.

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

You can use an enhanced method to check if the Walkthrough is loaded. Injector.isLoadedWalkthroughUnique() verifies whether the loaded Walkthrough is different than previously presented. Every time any Walkthrough is presented, its ID is cached locally, so you can control your flow more precisely.
The method will return true if the loaded Walkthrough is different than previously presented, false otherwise or if a Walkthrough is not loaded.

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

Delegate implementation

Here is a sample implementation of InjectorWalkthroughDelegate:

// MARK: - InjectorWalkthroughDelegate

// This method is called after a walkthrough is loaded.
// This method is invoked when the method 'SNR_walkthroughDidLoad:' is not implemented.
func snr_walkthroughDidLoad() {
  if Injector.isWalkthroughLoaded() {
    if Injector.isLoadedWalkthroughUnique() {
      Injector.showWalkthrough()
    }
  }
}

// This method is called after a walkthrough is loaded.
func snr_walkthroughDidLoad(walkthroughDictionary: [AnyHashable: Any]) {
  if Injector.isWalkthroughLoaded() {
    if Injector.isLoadedWalkthroughUnique() {
      Injector.showWalkthrough()
    }
  }
}

// This method is called when an error occurs while loading a walkthrough.
func snr_walkthroughLoadingError(error: Error) {
  print(error.localizedDescription)
}

// This method is called after a walkthrough appears.
func snr_walkthroughDidAppear() {
  //...
}

// This method is called after a walkthrough disappears.
func snr_walkthroughDidDisappear() {
  //...
}

Handling actions from campaigns

Note: SyneriseDelegate defines optional methods for handling actions from the whole SDK, but it can be used for handling campaign interactions. The descriptions below provide example implementations of these methods.

Synerise SDK handles three main actions that customer may invoke:

  • OPEN_APP
  • OPEN_URL
  • DEEPLINKING
Important: If you don’t configure a custom action for OPEN_URL, the SDK runs the default browser with the requested URL address.

In extended methods for handling URL and DEEP_LINKING, the following parameters are available:

  • SyneriseActivity: Enum type that defines the kind of activity from the action that was sent.
  • SyneriseActivityCompletionHandler: Block/closure that defines whether an activity should be hidden 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
  }
}

Common features

Blocking campaigns

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

To do this, add the 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 an activity, the activity is skipped.

Own implementation

You can also react to Synerise push notifications in your own way, using the payloads presented earlier in this article.

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

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

You can use the following methods to check the type of the incoming campaign payload:

Synerise.isSyneriseSimplePush(_:) - Checks if notification payload contains Simple Push campaign.

Synerise.isSyneriseBanner(_:) - Checks if notification payload contains Banner campaign.

Synerise.isSyneriseSilentCommand(_:) - Checks if notification payload contains Silent Command campaign.

Synerise.isSyneriseSilentSDKCommand(_:) - Checks if notification payload contains Silent SDK Command campaign.

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 {
    let isSyneriseBanner: Bool = Synerise.isSyneriseBanner(userInfo)
    if isSyneriseBanner {
      // default implementation by Synerise SDK
      // Synerise.handleNotification(userInfo)
      // or
      // your own implementation
    }

    completionHandler(UNNotificationPresentationOptions.init(rawValue: 0))
  } else {
    //...
  }
}

Push campaigns information

You can get pushes configured in app.synerise.com by using the 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.