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.

For more information, see the Method Reference.

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 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

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": "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": "https://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"
      }
    }
  ]
  }
}

Simple Push with Rich Media

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

Simple Push campaign supports two types of Rich Media extensions: Single Media and Image Carousel.

Incoming push payload

Single Media

{
    "aps":
    {
        "alert":
        {
            "title": "Your Simple Push Campaign title",
            "body": "Your Simple Push Campaign body"
        },
        "sound": "default",
        "badge": "5",
        "category": "synerise.notifications.category.single-media",
        "mutable-content": 1
    },
    "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_URL",
                "item": "https://www.example.com"
            }
        },
        "rich-media":
        {
            "type": "single-image",
            "single-image":
            {
                "image": "https://www.example.com/image.png"
            }
        }
    }
}
{
    "aps":
    {
        "alert":
        {
            "title": "Your Simple Push Campaign title",
            "body": "Your Simple Push Campaign body"
        },
        "sound": "default",
        "badge": "5",
        "category": "synerise.notifications.category.carousel"
    },
    "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_URL",
                "item": "https://www.example.com"
            }
        },
        "rich-media":
        {
            "type": "carousel",
            "carousel":
            {
                "orientation": "PORTRAIT",
                "items":
                [
                    {
                        "caption": "caption",
                        "subcaption": "Subcaption 1",
                        "image": "https://www.example.com/image.png",
                        "url": "https://www.example.com"
                    },
                    {
                        "caption": "caption",
                        "subcaption": "Subcaption 1",
                        "image": "https://www.example.com/image.png",
                        "url": "https://www.example.com"
                    },
                    {
                        "caption": "caption",
                        "subcaption": "Subcaption 1",
                        "image": "https://www.example.com/image.png",
                        "url": "https://www.example.com"
                    }
                ]
            }
        }
    }
}

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 user.

You can control incoming banners by implementing an optional delegate SNRInjectorBannerDelegate

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": {
    "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": "https://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 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.

Mandatory Upgrade

Mandatory upgrade is a banner that does not have a close button. The only thing a user 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

Configure Walkthrough

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

AUTOMATIC:

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

MANUAL:

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 SNRInjectorWalkthroughDelegate.

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.

Here is 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 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 user 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:

  • SNRSyneriseActivity: Enum type that defines the kind of activity from the action that was sent.
  • SNRSyneriseActivityCompletionHandler: 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
  }
}

Other 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 for campaigns

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.

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 Push Notifications campaigns data

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.