Campaigns

Simple push

Simple push is served by simple push notifications.

Note: Simple Push Campaigns are served by Push Notifications. To configure Push Notifications, see this article.

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.

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.

{
  "data": {
    "issuer": "Synerise",
    "message-type": "static-content",
    "content-type": "simple-push",
    "content": {
      "notification": {
        "title": "Finish your purchase",
        "body": "You have in your basket Road Bike RS-500 with discount for \"New Users\". Comeback to the basket and complete your purchase.",
        "icon": "https://upload.snrcdn.net/f2afa4d4d7af216196047d1f7f0613f22a50a8c8/default/origin/7eba69de2d4dab3a9388b9d72abd91eb.png",
        "action": {
          "type": "OPEN_APP"
        }
      },
      "buttons": [
        {
          "identifier": "check",
          "text": "Check",
          "action": {
            "type": "OPEN_URL",
            "item": "http://www.synerise.com"
          }
        },
        {
          "identifier": "view_similar",
          "text": "View similar",
          "action": {
            "type": "OPEN_URL",
            "item": "http://www.synerise.com"
          }
        }
      ],
      "campaign": {
        "hash_id": "196211cc-af48-4064-8860-aad986449322",
        "variant_id": 3175648,
        "type": "Mobile push",
        "title": "SimplePush For Docs"
      }
    }
  }
}

Available action types:

  • DEEP_LINKING
  • OPEN_URL
  • OPEN_APP

Available priority types:

  • NORMAL
  • HIGH

Content configuration in Synerise App

When creating the mobile simple push campaign in the Synerise App, in the content editor, perform the following steps:

  1. Fill in Title and Message.
  2. Switch device type to Android.
  3. Toggle the Image switch on.
  4. Insert the URL to your image file. Images can be uploaded in data management.
  5. Toggle the Action buttons switch on.
  6. Add a button and configure it. Add a name, action, and fill in the URL/Deep link field.
  7. As the action type, select Open app.

Example

A push with an action, image, and two clickable buttons. All user interactions are tracked with the use of Synerise Android SDK.

Note: The look of your push notifications may vary depending on Android versions.
Expanded simple push notification
Simple push notification presented on Android 10

Banners are served by silent push notifications.
Other campaign types, such as Mandatory Upgrade and First run message also use banners.

Note: Before you can start using this feature, you must configure push notifications. Click here for details.

Banners are presented only when your app is in the foreground. When the app is in the background or destroyed, a simple push appears instead.
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 the listener OnBannerListener:

  • Callback shouldPresent decides whether to show the incoming banner. By default, the SDK enables banner display.
  • Callback onPresented is fired when the banner is successfully created and presented to the customer.
    If the banner’s content is invalid, the banner is not presented and the callback is not fired.
  • Callback onClosed is fired when the banner is closed.
public static OnBannerListener NULL = new OnBannerListener() {
        @Override
        public boolean shouldPresent(TemplateBanner banner) {
            return true;
        }

        @Override
        public void onPresented() { }

        @Override
        public void onClosed() { }
    };

Payload

Banners can have the following layouts:

  • color_as_background
  • image_as_background
  • image_with_text_atop
  • image_with_text_below
{
  "notification": {
    "title": "Notification title",
    "body": "Notification body"
  },
  "data": {
    "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
      }
    }
  }
}
Important:

When the app is not running, the banner appears as a notification with the default Firebase notification icon (your application’s icon).
If you want to set another icon, modify the Android manifest file:

<meta-data
            android:name="com.google.firebase.messaging.default_notification_icon"
            android:resource="@drawable/your_icon_here" />

Triggers

In order to show a banner immediately after a certain event occurred, you can send your banners from the Synerise panel with a trigger value.

When Injector.fetchBanners is called, it fetches all available banners, and then SDK caches those that are valid. You receive an array of banners formatted as a dictionary.

This method is also called during SDK initialization, so use it only when you wish to overwrite the current banners in SDK cache.

Injector.getBanners() provides valid banners directly from the SDK cache.

Note: The exact same banners are being searched for eventual campaign triggers.

You can keep banner data from:

Next, call Injector.showBanner(banner, markPresented) to show a banner immediately.

Content configuration in Synerise App

When creating the banner push campaign in the Synerise App, in the content editor, perform the following steps:

  1. As the layout type, select Full screen image.
  2. Fill in the Image URL field.
  3. Toggle the Close button switch on.
  4. Choose the position of the close button.
  5. Toggle the Automatically disappear switch on.
  6. Enter the timeout in seconds.
  7. Choose an action type.

Example

This is a banner with a background image.

Banner example
In-app banner

Walkthrough


Synerise SDK provides multiple functionalities within Walkthrough implementation.

You can specify Walkthrough behavior when the SDK initializes:

Synerise.Builder.with(this, syneriseClientApiKey, appId)
        .notificationIcon(R.drawable.ic_notification_icon)
        .injectorAutomatic(true)
        .build();

Setting .injectorAutomatic(true) will fetch the Walkthrough right away. That Walkthrough will be presented the moment it gets loaded, atop of your current Activity, if the ID of the walkthrough is different than previously presented.

Note that the walkthrough is a translucent activity, so your activity’s onStop() method may not be called. Also, the walkthrough activity is launched with the FLAG_ACTIVITY_NEW_TASK flag, so you can handle your activity stack properly. To control this behavior, fetch your Walkthrough manually with Injector.getWalkthrough().

This method cancels the previous API request (if any) and then starts loading Walkthrough asynchronously. It must be called after Injector.setOnWalkthroughListener(OnWalkthroughListener) to receive callbacks properly. See the Optional callbacks section.

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

There is also an enhanced method to check if 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 returns 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 the Walkthrough was loaded, false otherwise.

Optional callbacks

When you choose to load and present a Walkthrough manually, you may use the following callbacks:

Injector.setOnWalkthroughListener(new OnWalkthroughListener() {
            @Override
            public void onLoadingError(ApiError error) {
                error.printStackTrace();
                goDashboard();
            }
            @Override
            public void onLoaded() {
                if (Injector.isLoadedWalkthroughUnique()) {
                    Injector.showWalkthrough();
                } else {
                    goDashboard();
                }
            }
            @Override
            public void onPresented() {
                super.onPresented();
            }
            @Override
            public void onClosed() {
                super.onClosed();
            }
        });

Note that all these methods are optional and overriding them is not required. These are also called when a Walkthrough was loaded automatically.

  • onLoadingError(ApiError) - This callback is fired the moment after a Walkthrough failed to get initialized. This error may be caused by unsuccessful API response or invalid Walkthrough content.
    An ApiError instance is provided to check the cause of the error.
  • onLoaded() - This callback is fired the moment after a Walkthrough is initialized successfully. Remember that the Walkthrough will be shown automatically if Synerise.Builder.injectorAutomatic(boolean) was set to true and if the ID of the Walkthrough is different than previously presented.
  • onPresented() - This callback is fired when a Walkthrough is successfully created and will be presented to the customer. Note that Walkthrough will not be presented to customer if its content is invalid, and therefore callback will not be fired.
  • onClosed() - This callback is fired when a Walkthrough is closed (just before actually closing).

Remember to remove the Walkthrough listener to stop receiving callbacks:

Injector.removeWalkthroughListener();

Silent push

Synerise SDK provides features such as remote sign out or acquiring location by using a silent push command.

This kind of campaign does not affect your UI. Silent push notification is usually a trigger for some business logic.

Silent notifications made by Synerise are handled by Injector.handlePushPayload

You can also check if a notification is a silent command by using Injector.isSilentCommand method.
For Synerise silent command, you can use Injector.isSilentCommandSdk.

When you choose to have your custom implementation of silent commands, you may use the following in your FirebaseMessaggingService:

@Override
    public void onMessageReceived(RemoteMessage remoteMessage) {
        super.onMessageReceived(remoteMessage);

        Map<String, String> data = remoteMessage.getData();
        if (Injector.isSilentCommand(data)) {
            try {
                SilentCommand silentCommand = Injector.getSilentCommand(data);
                // your logic here
            } catch (ValidationException e) {
                e.printStackTrace(); 
            }

More information about SilentCommand can be found in our class reference.

Payload

This payload retrieves location from a customer. Synerise Android SDK triggers a callback to get location from the app. As a result, the SDK sends an event with the customer’s location.

{
  "data": {
    "issuer": "Synerise",
    "message-type": "dynamic-content",
    "content-type": "silent-sdk-command",
    "content": {
      "class_name": "com.synerise.sdk.injector.Injector",
      "method_name": "GET_LOCATION",
      "method_parameters": []
    }
  }
}

Common features

Handling app invisibility

If an app was invisible to a customer (minimized or destroyed) and a campaign banner is received - the simple push message is presented to the customer and launcher activity is fired after the notification is clicked.
This is the best moment to pass this data and the SDK verifies if it is a campaign banner.
If it is, the banner is presented within the app (atop of your activities). Please note that banner is a translucent activity, so your activity’s onStop() method may not be called.
Banner activity is launched with the FLAG_ACTIVITY_NEW_TASK flag, so you can handle your activity stack properly.
If your launcher activity lasts quite longer, check the onNewIntent(Intent) implementation below.

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_main);

        boolean isSynerisePush = Injector.handlePushPayload(getIntent().getExtras());
    }
Note: The Injector.handlePushPayload(getIntent().getExtras()); method must be called to handle notifications by SyneriseSDK.

When your launcher activity takes more time, you might be interested in the onNewIntent(Intent) method.
In this case, it is preferred to override this method.
This is because when a campaign banner is received while the app is minimized, a simple push is presented to the customer in the system tray.
If your launcher activity was already created and the notification was clicked, your onCreate(Bundle) method will not be called.

    @Override
    protected void onNewIntent(Intent intent) {
        super.onNewIntent(intent);
        setIntent(intent);
        boolean isSynerisePush = Injector.handlePushPayload(intent.getExtras());
    }

Own implementation (simple push, banner)

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 nad what data is included.

  • Injector.isSynerisePush(Map<String, String>) only checks whether the provided push data comes from Synerise.
    It is validated by checking if the incoming push contains the “issuer” key with the “Synerise” value.
  • Injector.isSyneriseSimplePush(Map<String, String>) only checks whether the provided push data comes from Synerise and if it is specifically a Synerise Simple Push.
    It is validated by checking if the incoming push contains the “content-type” key with the “simple-push” value.
  • Injector.isSyneriseBanner(Map<String, String>) only checks whether the provided push data comes from Synerise and if it is specifically a Synerise Banner.
    It is validated by checking if the incoming push contains the “content-type” key with the “template-banner” value.
  • Injector.isSilentCommand only checks whether the provided push data comes from Synerise and if it is specifically a Silent Command.
    It is validated by checking if the incoming push contains the “content-type” key with the “silent-command” value.
  • Injector.isSilentSdkCommand only checks whether the provided push data comes from Synerise and if it is specifically a Silent SDK Command.
    It is validated by checking if the incoming push contains the “content-type” key with the “silent-sdk-command” value.

Campaign pushes information

Injector.getPushes() gets all available simple and silent pushes for a customer.

IDataApiCall with parameterized list of SynerisePushResponse is returned to execute request.

😕

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.