Campaigns

Introduction

Campaign 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.Notifications.isNotificationSimplePush(_:) let you check if the incoming content is of the expected type.

Simple push

If an app is not active (is closed or running in the background) when 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 Android and iOS versions.

Simple Push with Rich Media - iOS only

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

Simple Push campaign support 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 by using 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 by using 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 listener IInjectorBannerListener

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 occurs, you can send your banners from app.synerise.com with a TRIGGER value.

Banners are fetched during SDK initialization and while the application is running, these banners are searched for campaign triggers.

Additionally, you can process banners on demand:

  1. Get banner data in one of the following ways:
    • Synerise.Injector.fetchBanners(onSuccess: (banners: Array<Object>) => void, onError: (error: Error) => void) - fetch available banners (the SDK refreshes the cache).
    • Synerise.Injector.getBanners(): Array<Object> - get available banners from the SDK cache.
  2. Call the banner immediately by calling the Synerise.Injector.showBanner(banner: Object, markPresented: boolean) method.

Listener implementation

Here is a sample implementation of IInjectorBannerListener:

Synerise.Injector.setBannerListener({
  onPresent: function() {
    //...
  },
  onHide: function() {
    //...
  }
});
Important: If you don’t want to show any of the Synerise banner campaigns, call the Synerise.Injector.setShouldBannerPresentFlag(shouldPresentBanner: boolean) with false as the argument.

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 a number of 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 mode 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 Synerise.Injector.getWalkthrough(). It must be called after setting up IInjectorWalkthroughListener.

You can check if the Walkthrough is already loaded with the Synerise.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. Synerise.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.

Synerise.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 the Walkthrough was loaded, false otherwise.

Handling actions from campaigns

Note: The Injector Listener defines optional methods for handling actions from the whole SDK, but it can be used for handling campaign interactions. The description below is an implementation of these methods.

Synerise SDK handles two main actions that a customer may invoke:

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

Example implementation

Synerise.Injector.setListener({
  onOpenUrl: function(url) {
    //url implementation
    Linking.openURL(url);
  },
  onDeepLink: function(deepLink) {
    //your custom deeplinking implementation
  }
  //...
  //other listener's methods
});

Common features

Own implementation

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

If you need to know whether an incoming push message comes from Synerise, use theSynerise.Notifications.isSyneriseNotification(payload: Object) method. The source of the notification 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.Notifications.isSyneriseSimplePush(payload: Object) - Checks if the notification payload contains a Simple Push campaign.

Synerise.Notifications.isSyneriseBanner(payload: Object) - Checks if the notification payload contains a Banner campaign.

Synerise.Notifications.isSyneriseSilentCommand(payload: Object) - Checks if the notification payload contains a Silent Command campaign.

Synerise.Notifications.isSyneriseSilentSDKCommand(payload: Object) - Checks if the notification payload contains a Silent SDK Command campaign.

Synerise.Notifications.setListener({
  onNotification: function(payload) {
    if (Synerise.Notifications.isSyneriseNotification(payload)) {
      // default implementation by Synerise SDK
      // Synerise.handleNotification(userInfo)
      // or
      // your own implementation
    } else {
      //...
    }
  }
  //...
  //other listener's methods
});
😕

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.