Skip to content

Commit

Permalink
Merge pull request #103 from notificationapi-com/BDA8wsF6/2172-update…
Browse files Browse the repository at this point in the history
…-docs-for-in-app-batching

Simplify batching and add in-app batching
  • Loading branch information
sahandseifi authored Jul 17, 2024
2 parents 64c03bc + 287b469 commit fbd56a8
Show file tree
Hide file tree
Showing 19 changed files with 4,062 additions and 3,555 deletions.
4 changes: 2 additions & 2 deletions .github/workflows/publish.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,9 +18,9 @@ jobs:
if [ -e yarn.lock ]; then
yarn install --frozen-lockfile
elif [ -e package-lock.json ]; then
npm ci
npm ci --force
else
npm i
npm i --force
fi
npm run build
Expand Down
2 changes: 1 addition & 1 deletion docs/channels/inapp.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ Any JavaScript based front-end framework, including:
You don't need any database or other APIs. We manage all the necessary storage and APIs under-the-hood. Our widget automatically connects to our servers and gets the job done.
:::

The widget is open-sourceand fully customizable. You can modify the look and feel to match your brand or fork it to change the behavior. Alternatively, you can write your own UI from scratch. You can use our REST API to fetch the notifications, mark them as read, etc. However, our team is happy to take any feature requests and apply them to our open-source widget.
The widget is open-source and fully customizable. You can modify the look and feel to match your brand or fork it to change the behavior. Alternatively, you can write your own UI from scratch. You can use our REST API to fetch the notifications, mark them as read, etc. However, our team is happy to take any feature requests and apply them to our open-source widget.

## Important Features

Expand Down
2 changes: 1 addition & 1 deletion docs/features/_category_.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
{
"label": "Other Features",
"label": "Features",
"position": 3
}
115 changes: 78 additions & 37 deletions docs/features/digest.md
Original file line number Diff line number Diff line change
@@ -1,79 +1,116 @@
# 📦 Batch & Digest
# 📦 Batching & Digest

:::note
The NotificationAPI's Batch & Digest allows for combining multiple notifications into one. The resulting batched notification can be designed with our editors, and can be configured to be sent at different intervals (hourly, daily, ...).

Status: Batch & Digest is currently in active development. Stay tuned for more updates and improvements.
## Common Use Cases

:::

The NotificationAPI's Batch & Digest feature allows for the creation of recurring user digests at configured intervals. By batching multiple notifications into one, it effectively reduces notification fatigue. This feature is particularly useful for weekly reports or user digests. The notification editor provides a versatile tool for customizing the appearance of combined notifications, and your users can set their preferred schedule if needed.

## Example Use Cases

- Social media post likes and comments: In social media platforms, each like and comment on a post generates an event. Instead of sending separate notifications for each event, the Batch and Digest feature consolidates these into a single notification. At your chosen time, the requests will be compiled and sent a summarized report of all interactions on the post.

- Truck Driver Schedule: For administrators overseeing food supply chains, a daily overview of all pickups and deliveries is crucial. The Digest feature provides these summaries, promoting effective and timely operations management.
**Preventing notification fatigue**: For example, instead of sending 10 "new comment" emails, you can batch them into one "new comments" email on an hourly basis.

## How does it work?
**Daily/Weekly/Monthly Reports**: You can combine the "events" from your software into a daily/weekly/monthly email. For example, every time there is a new user you can trigger a notification, but our system will send a "new users this week" email on a weekly basis.

For each notification, you can configure the channels' `Delivery Options` as following:
## Email Batching - How does it work?

- `Instantly`: When we receive an `Email` request, we try to deliver it to your user instantly. This delivery option is the `default`.
- `Hourly`: We deliver all the `Email` requests that we receive in an hour.
- `Weekly`: This configuration delivers all the `Email` requests once a week. You can choose the day and time for it.
- `Monthly`: To deliver `Email` notifications once a month. It can happen at the beginning or end of a month. You can also select the time to deliver as well.
- `Allow unsubscribing`: This allows your users to unsubscribe from this `Email`.
### 1. Configure

`The Default Preference` indicates your users' default preference for delivery options.

The following shows a sample of an `Email` channel's `Delivery Options`.
From our dashboard, you can enable different `Delivery Options` for the email channel.

import deliveryOptions from '@site/static/delivery_options.png';
import userPreference from '@site/static/userPreference.png';

<img
src={deliveryOptions}
style={{
maxWidth: 480,
borderRadius: 20,
border: '1px solid #d9d9d9',
marginLeft: 100
marginBottom: 20
}}
/>

If you adjust the settings in the above component, the default [user preference prebuilt component](../components/user-preferences.md) will be displayed as follows:`
In the example above, we are allowing users to receive emails intantly (no batching) or to unsubscribe from this email. The default delivery method for new users is based on the small green tag, which you can change.

The above options also allow users to see and pick the right preference for themselves using our [prebuilt user preference component](../components/user-preferences.md):

import userPreference from '@site/static/UserPreferencesEmailBatching.png';

<img
src={userPreference}
style={{
maxWidth: 480,
borderRadius: 20,
border: '1px solid #d9d9d9',
marginLeft: 100
borderRadius: 2
}}
/>

Each channel can have one or more templates, and each template can be configured for one or multiple delivery options.
### 2. Configure the Template

Using the example `new_comment` notification above, you can configure the `Email` channel to deliver every Monday at 9:00 am via enabling the `Weekly` option and choosing `Monday 9:00 am` from the dropdown boxes. Doing so will give your notification three delivery options: `Instantly`, `Weekly` and `Allow Unsubscribing`. You can optionally choose to have the `Weekly` option as the default, via selecting it in `The Default Preference` options.
Don't forget to create and assign an email template for the batched delivery options. For example, if you have enabled the `Weekly` delivery option, you must create a template and from its options, pick it as the template used for the `Weekly` emails.

In the design tab, you can create two `Email` templates: one for the `Instantly` delivery option and one for `Weekly.` Requests sent for this notification will be batched and on `Monday at 9:00 am` the notification will send on its `Email` channel using the `Weekly` template. If your user changes their `Email` preference to `Instantly`, then the notification will be sent instantly with the corresponding `Instantly` template.
:::tip

When using [Parameters (Merge Tags)](./mergetags) while you are desiging a template, you can access the batched items via `{{_items}}`. This parameter is an array of all requests that were batched since the notification was last sent and delivered based on your `Delivery Options`.
You can create unlimited templates for each notification type. For example, you can have a "default" template for the `new_comment` email notification, a "Spanish" template for Spanish speaking users, or a "Weekly Digest (English)" template for batching these notifications into a single email.

For example, you can retrieve the number of comments in the `new_comment` notification by using a [`filter`](./mergetags#filters) like `{{_items | size}}` in your template. This parameter will be replaced with the number of requests in the current batch.
:::

### 3. Designing the Template

You can design the batch template using our no-code email editor, just like you would with a regular instant email.

Tips:

- When using [Parameters (Merge Tags)](./mergetags), you can access the batched items via `{{_items}}`.
- To count the number of batched items, you can use `{{_items.size}}` in your template.
- You can repeat a row based on the `_items` by selecting the row and clicking the "Select Condition" button on the right panel.

With batching you can still use all the functionality that is provided by the [Parameters (Merge Tags)](./mergetags.md) feature, such as [`Loops`](./mergetags#loops-for), [`Conditional Logic`](./mergetags#conditional-logic-if-else), and [`filter`](./mergetags#filters).
import EmailEditorBatching from '@site/static/EmailEditorBatching.png';

<img
src={EmailEditorBatching}
style={{
maxWidth: 800,
borderRadius: 2
}}
/>

## In-App Batching

In-App batching works different than email in the sense that it happens live. When a new in-app notification is generated, it is instantly sent to the client-side SDK, and then client-side SDK handles the batching.

### 1. Configure

From our dashboard, you can select that the in-app notifications should be batched. When selecting this option, you are allowed to pick how notifications are batched together by picking a `batchingKey`.

Notifications with similar `batchingKeys` are batched together. For example, when users make comments under a social media post, you can use that post's unique ID as the `batchingKey`. This way, the new comment notifications for the same post are batched together. For this purpose, you can set the batchingKey to `{{parameters.comment_id}}`.

### 2. Design the Template

In the in-app template editor, you now have the option to specify the title, image and URL of the batched in-app notifications. For example, instead of displaying "You have a new comment", you can display "You have \{\{\_items.size\}\} new comments".

import InAppEditorBatched from '@site/static/InAppEditorBatched.png';

<img
src={InAppEditorBatched}
style={{
maxWidth: 600,
borderRadius: 2
}}
/>

### 3. SDK

The React SDK automatically handles the batching logic and UI on the client-side.

:::tip[If you have built your own UI]
We pass everything you need for the batching logic and UI inside the in-app notification objects. You can even create your own custom batching logic that batches notifications based on whatever criteria you need.
:::

## Frequently Asked Questions (FAQs)

### How does `Batch & Digest` work when there are no requests at the delivery time configured in the `Delivery Options`?
### How does `Email Batching` work when there are no requests at the set hour/day/week/month?

If there are no notifications for a user in the specified period, the system will not send a notification. For example, assume you have selected the `Weekly` delivery option on `Monday at 9:00 am` for the `Email` channel. If there is no request recorded for the user by `Monday at 9:00 am` then no email will be sent.
If there are no notifications for a user in the batch period, the system will not send an email.

### Will notifications with different sub notifications be batched together or separately?

Requests with different [sub notifications](./scheduling.md) will be batched separately.
Requests with different [subNotificationIds](./scheduling.md) will be batched separately.

### How does `Batch & Digest` work with `Throttling`?

Expand All @@ -93,6 +130,10 @@ Batched notifications are sent based on their selected `Delivery Options`. Any r

For example, assume a notification is configured to send batches `Weekly` on `Monday at 9:00 am`, and recieves a scheduled request for `Sunday at 1:00 pm`. The request is not sent on `Sunday at 1:00 pm`: instead it is batched and will be included in the notification sent on `Monday at 9:00 am`.

### What happens to email attachments?

Batched notifications will retain and combine all of their attachments into the same email. You should be careful with the size of the attachments.

### Do I have to pay extra for `Batch & Digest`?

No, this feature is provided for no additional charge.
1 change: 1 addition & 0 deletions docs/features/mergetags.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ You can use merge tags almost everywhere:

- Email Subject Line
- Email Content: Text, Button Link, Image Link, ...
- `From Address` and `From Name` in Template Editor
- All fields of In-App, SMS, Call, Mobile Push and Web Push

## Passing the values
Expand Down
2 changes: 1 addition & 1 deletion docs/intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ Intercom('show');
#### Client-Side

<div style={{display: 'flex', flexWrap: 'wrap', columnGap: 64, rowGap: 32, marginBottom: 32}}>
<SupportedEnvironment logo="devicon-react-plain" name="React" path="./reference/js-client" />
<SupportedEnvironment logo="devicon-react-plain" name="React" path="./reference/react-sdk" />
<SupportedEnvironment logo="devicon-nextjs-plain" name="Next.js" path="./reference/js-client" />
<SupportedEnvironment logo="devicon-javascript-plain" name="JavaScript" path="./reference/js-client" />
<SupportedEnvironment logo="devicon-angularjs-plain" name="Angular" path="./reference/js-client" />
Expand Down
2 changes: 1 addition & 1 deletion docs/quick-start/display-inapp-notifications.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ import InAppPNG from '@site/static/inapp.png';

## Playground

[See a demo and modify the code here on CodeSandbox](https://codesandbox.io/s/notificationapi-in-app-notifications-demo-l91923?file=/index.js).
[You can see and modify the code here on our in-app playground](../features/mergetags#playground).

## Step 1: Install the Front-End SDK

Expand Down
24 changes: 12 additions & 12 deletions docs/reference/android-sdk.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
---
sidebar_position: 4
sidebar_position: 6
---

# Android SDK (Front-End)
# Android SDK

The Android SDK is used to recieve **push notifications** and handle device token synchronization with NotificationAPI.

Expand Down Expand Up @@ -74,7 +74,7 @@ class MainActivity : NotificationApiActivity() {
companion object {
const val TAG = "Example App"
}

override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
Expand Down Expand Up @@ -106,15 +106,15 @@ class MainActivity : NotificationApiActivity() {
}
```

You must configure the SDK with your `NotificationAPI` credentials. It is recommended to configure the SDK as early as possible. You must also request notification authorization from the user.
You must configure the SDK with your `NotificationAPI` credentials. It is recommended to configure the SDK as early as possible. You must also request notification authorization from the user.

You are now ready to recieve push notifications from NotificationAPI! :tada:

## NotificationApiService

The `NotificationApiService` class handles device token synchronization with NotificationAPI. It is required to extend from this class in order to recieve push notifications from NotificationAPI.

### fun onPreDisplayNotification(message: RemoteMessage)
### fun onPreDisplayNotification(message: RemoteMessage)

This function is called after `NotificationApiService` has recieved a notification but before displaying the notification. You can override `onPreDisplayNotification()` to customize how the notification will be displayed. To use the default notification display, you must call `displayNotification()` here.

Expand All @@ -131,18 +131,18 @@ NotificationAPI sends notification data through Firebase as data messages instea

:::

### fun displayNotification(intent: NotificationApiIntent, icon: Int, channelId: String, channelName: String): Int
### fun displayNotification(intent: NotificationApiIntent, icon: Int, channelId: String, channelName: String): Int

This function displays a default notification to the given notification channel. This will create the notification channel if it does not exist. You should call this within `onPreDisplayNotification()` to actually display the notification to the user.

#### Parameters

`intent` (required)
`intent` (required)
Type: NotificationApiIntent

An intent that contains the notification click handler as well as the remote message that will be displayed.

`icon` (required)
`icon` (required)
Type: Int

The icon to display for the notification.
Expand All @@ -161,7 +161,7 @@ The user friendly name of the channel to display the notification in. Defaults t

An UUID for the displayed notification.

### fun onNewToken(token: String)
### fun onNewToken(token: String)

This function is called when FCM generates a new device token.

Expand All @@ -188,7 +188,7 @@ This function is called when a notification has been clicked on by an user.

#### Parameters

`message`
`message`
Type: [RemoteMessage](https://firebase.google.com/docs/reference/kotlin/com/google/firebase/messaging/RemoteMessage)

The notification that was clicked on.
Expand Down Expand Up @@ -252,7 +252,7 @@ Type: String

Your NotificationAPI client id.

`userId` (required)
`userId` (required)
Type: String

The user id.
Expand All @@ -273,4 +273,4 @@ A data class for NotificationApi credentials
`baseUrl` (required)
Type: String

The NotificationAPI API base url.
The NotificationAPI API base url.
16 changes: 9 additions & 7 deletions docs/reference/ios-sdk.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
---
sidebar_position: 3
sidebar_position: 5
---

# iOS SDK (Front-End)
# iOS SDK

The iOS SDK is used to recieve **push notifications** and handle device token synchronization with NotificationAPI.

Expand All @@ -12,7 +12,7 @@ Supported environments:

## Setup

You can follow Apple's instructions for installing a package dependency [here](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app).
You can follow Apple's instructions for installing a package dependency [here](https://developer.apple.com/documentation/xcode/adding-package-dependencies-to-your-app).

The URL is `https://github.com/notificationapi-com/notificationapi-ios-sdk.git`

Expand All @@ -24,17 +24,17 @@ We highly recommend to extend from `NotificationApiAppDelegate.swift` and use th
class AppDelegate: NotificationApiAppDelegate {
func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey : Any]? = nil) -> Bool {
NotificationApi.shared.configure(withCredentials: NotificationApiCredentials(clientId: "YOUR_CLIENT_ID", userId: "YOUR_USER_ID"))

NotificationApi.shared.requestAuthorization { granted, _ in
print("Is authorized?: \(granted)")
}
}

return true
}
}
```

You must configure the SDK with your `NotificationAPI` credentials. It is recommended to configure the SDK as early as possible. You must also request notification authorization from the user.
You must configure the SDK with your `NotificationAPI` credentials. It is recommended to configure the SDK as early as possible. You must also request notification authorization from the user.

You are now ready to recieve push notifications from NotificationAPI! :tada:

Expand Down Expand Up @@ -86,7 +86,7 @@ Your NotificationAPI credentials. You can retrieve them from [here](https://app.
`config`
Type: NotificationApiConfig

Config object for the NotificationApi SDK.
Config object for the NotificationApi SDK.

### func requestAuthorization(completionHandler handler: @escaping (Bool, Error?) -> Void)

Expand Down Expand Up @@ -118,6 +118,7 @@ There is also an async version that can be used like the following:
```swift
func NotificationApi.shared.requestAuthorization() async throws -> Bool
```

:::

### func syncApn(token: String, completionHandler handler: @escaping (Error?) -> Void)
Expand Down Expand Up @@ -145,6 +146,7 @@ There is also an async version that can be used like the following:
```swift
func syncApn(token: String) async throws
```

:::

## NotificationApiCredentials
Expand Down
4 changes: 2 additions & 2 deletions docs/reference/js-client.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
---
sidebar_position: 2
sidebar_position: 3
---

# JS Client SDK (Front-End)
# Vanilla JS (Front-End)

The client-side SDK is mainly used for displaying **In-App Notifications** and allowing users to see and change their **Notification Preferences**.

Expand Down
Loading

0 comments on commit fbd56a8

Please sign in to comment.