Push Notifications

Android

To use Push Notifications out of the box using CleverTap, add the following entries to your AndroidManifest.xml

<application>
         ....
         ....
        <service android:name="com.clevertap.android.sdk.pushnotification.fcm.FcmMessageListenerService" 
         android:exported="true">
            <intent-filter>
                <action android:name="com.google.firebase.MESSAGING_EVENT" />
            </intent-filter>
        </service>

 </application>

📘

Notification trampolines in Android 12 and above.

To improve performance, Android has changed the handling of push notifications for version 12 and above. An app is no longer allowed to start an activity from within a service or broadcast receiver. For more information, refer to Android 12 Push Changes.

Creating Notification Channel

CleverTapPlugin.createNotificationChannel("fluttertest", "Flutter Test", "Flutter Test", 3, true);

Delete Notification Channel

CleverTapPlugin.deleteNotificationChannel(“channelId”);

Creating a group notification channel

CleverTapPlugin.createNotificationChannelGroup(“groupId”, “groupName”);

Delete a group notification channel

CleverTapPlugin.deleteNotificationChannelGroup(“channelId”);

Push Notification Callback

The CleverTap SDK gives you a callback when a Push Notification is clicked along with the entire payload. For this You can register the setCleverTapPushClickedPayloadReceivedHandler callback .

CleverTapPlugin _clevertapPlugin = new CleverTapPlugin();
_clevertapPlugin.setCleverTapPushClickedPayloadReceivedHandler(pushClickedPayloadReceived);


 void pushClickedPayloadReceived(Map<String, dynamic> map) {
    print("pushClickedPayloadReceived called");
    this.setState(() async {
      var data = jsonEncode(map);
      print("on Push Click Payload = " + data.toString());
    });
  }

Setting a custom Push Notification icon.

By default, our SDK uses the app's icon for both the notification icon and the notification bar icon. However, You can provide a custom app icon by adding the icon in your app's android resources and registering it with clevertap in your AndroidManifest.xml
Checkout this section for more info.

Custom Push Notification Handling

If you have your custom implementation for managing Android push notifications, you can inform CleverTap about the user’s Push Service Registration ID :

Custom FCM Implementation

CleverTapPlugin.setPushToken("fcm_token");

Custom Baidu Implementation

CleverTapPlugin.setBaiduPushToken("baidu_token");

Custom Huawei Implementation

CleverTapPlugin.setHuaweiPushToken("huawei_token");

Custom Xiaomi Implementation

CleverTapPlugin.setXiaomiPushToken("xiaomi_token");

Push Notification Templates

CleverTap Push Templates SDK helps you engage with your users using fancy push notification templates built specifically to work with CleverTap.
It requires no Flutter-specific integration and can be enabled via android code only. Find the complete integration steps for the CleverTap Push Templates SDK here and the associated documentation here

Push Notifications Permission

Starting from Android 13 and iOS 10.0, applications must request notification permission from the user before sending Push Notifications. All newly-installed applications must seek user permission before they can send notifications.

Push Primer

A Push Primer explains the need for push notifications to your users and helps to improve your engagement rates. It is an InApp notification that you can show to your users before requesting notification permission.

Push Primer helps with the following:

Allows you to educate your users on why you are asking for this permission before invoking a system dialog to seek user permission.
Acts as a precursor to the hard system dialog and thus allows you to seek permission multiple times if previously denied without making your users search the device settings.

Starting with the v1.6.0 release, CleverTap Flutter SDK supports Push primer for push notification runtime permission through local in-app.

📘

iOS and Android Versions for Push Primer

• The minimum supported version for the iOS platform is 10.0.
• The minimum supported version for the Android platform is Android 13.

The following are the two ways to handle the new push notification changes:

1. Push Primer Using Half-Interstitial InApp Notification Template
2. Push Primer Using In-App Alert Template

Push Primer Using Half-Interstitial InApp Template

Using this template, you can send a customized push primer notification with an image, text, and button. You can also modify the notification's text, button, and background color.
Refer to the following images for Push Primer using Half-Interstitial InApp Template:

• In Android

• In iOS

Add the following code to your code to create Push Primer using the Half-Interstitial InApp template:

var pushPrimerJSON = {
  'inAppType': 'half-interstitial',
  'titleText': 'Get Notified',
  'messageText': 'Please enable notifications on your device to use Push Notifications.',
  'followDeviceOrientation': false,
  'positiveBtnText': 'Allow',
  'negativeBtnText': 'Cancel',
  'fallbackToSettings': true,
  'backgroundColor': '#FFFFFF',
  'btnBorderColor': '#000000',
  'titleTextColor': '#000000',
  'messageTextColor': '#000000',
  'btnTextColor': '#000000',
  'btnBackgroundColor': '#FFFFFF',
  'btnBorderRadius': '4',
  'imageUrl': 'https://icons.iconarchive.com/icons/treetog/junior/64/camera-icon.png'
};
CleverTapPlugin.promptPushPrimer(pushPrimerJSON);

Push Primer using Alert InApp Template

Using this template, you can create a basic push primer notification with a title, message, and two buttons.
Refer to the following images for Push Primer using the Alert InApp template:

• In Android

• In iOS

Add the following code to your code to create a Push Primer using the Alert InApp template:

var pushPrimerJSON = {
  'inAppType': 'alert',
  'titleText': 'Get Notified',
  'messageText': 'Enable Notification permission',
  'followDeviceOrientation': true,
  'positiveBtnText': 'Allow',
  'negativeBtnText': 'Cancel',
  'fallbackToSettings': true
};
CleverTapPlugin.promptPushPrimer(pushPrimerJSON);

Method Description

The following table describes all the keys used to create In-App templates:

Invoke Notification Permission Dialog without Push Primer

You can call the push permission dialogue directly without a Push Primer using the promptForPushNotification(boolean) method. It takes a boolean value as a parameter.

• If the value is set to true and permission is denied, then the user is redirected to the app’s notification settings.
• If the value is set to false, the callback is sent stating that the permission is denied.

var fallbackToSettings = false;
CleverTapPlugin.promptForPushNotification(fallbackToSettings);

Check the Push Notification Permission Status

The isPushPermissionEnabled method can be used to check the status of the push notification permission for your application. The method returns the status of the push permission.

bool? isPushPermissionEnabled = await CleverTapPlugin.getPushNotificationPermissionStatus();
if (isPushPermissionEnabled == null) return;

if (!isPushPermissionEnabled) {
  // call Push Primer here.
} else {
  print("Push Permission is already enabled.");
}

Available Callback for Push Primer

Based on notification permission grant/deny, CleverTap Flutter SDK provides a callback with the permission accepted status.

_clevertapPlugin.setCleverTapPushPermissionResponseReceivedHandler(pushPermissionResponseReceived);

void pushPermissionResponseReceived(bool accepted) {
  print("Push Permission response called ---> accepted = " + (accepted ? "true" : "false"));
}

iOS

1. Refer to iOS Push Notifications setup and follow the same steps till step 4 in the document and in your runner application in Xcode, please configure the push notifications in your Flutter project.

2. Call the following from your Dart:

CleverTapPlugin.registerForPush();

3. Now go to this page on how to create a push notification Campaign on CleverTap dashboard or you can follow the remaining steps on CleverTap iOS Push Notifications page

iOS Push Notification Templates

CleverTap iOS Push Templates allow you to engage with users using rich push notification templates. For more details about rich push notifications templates, refer to iOS Rich Push Notifications.

Flutter Push Notification Callback on iOS

The CleverTap SDK gives you a callback when a Push Notification is clicked along with the entire payload. For this, You can register the CleverTapPushNotificationClicked callback.

CleverTapPlugin.pushNotificationClickedEvent();

You can raise a callback event if a notification is viewed on Flutter Application.

CleverTapPlugin.pushNotificationViewedEvent();

Deeplink or External URL (iOS)

A deeplink helps you open a particular activity in your app after a click on the notification. If left empty, the notification on click will open the launcher activity of the app. Deep links allow you to land the user on a particular part of your app. Your app's OpenURL method is called with the deep link specified here. If you want to use external URLs, you will have to whitelist the IPs or provide http/https before the URL so that the SDK can appropriately handle them. For more information, refer to Deeplinking.

With CleverTap Flutter SDK, you can implement custom handling for URLs of in-app notification CTAs, push notifications, and app Inbox messages.

Check that your class conforms to the CleverTapURLDelegate protocol by first calling setURLDelegate. Use the following protocol method shouldHandleCleverTap(_ : forChannel:) to handle URLs received from channels such as in-app notification CTAs, push notifications, and app Inbox messages:

#import <CleverTapSDK/CleverTapURLDelegate.h>

// Set the URL Delegate
[[CleverTap sharedInstance]setUrlDelegate:self];

// CleverTapURLDelegate method 
- (BOOL)shouldHandleCleverTapURL:(NSURL *)url forChannel:(CleverTapChannel)channel {
    NSLog(@"Handling URL: \(%@) for channel: \(%d)", url, channel);
    return YES;
}

// Set the URL Delegate
CleverTap.sharedInstance()?.setUrlDelegate(self)


 // CleverTapURLDelegate method
public func shouldHandleCleverTap(_ url: URL?, for channel: CleverTapChannel) -> Bool {  
    print("Handling URL: \(url!) for channel: \(channel)") 
    return true 
}

Manually Enabling support for deeplink tracking in the application

To manually enable support for deeplink tracking in the application itself, refer to iOS Deeplink Tracking.