Skip to content

Commit

Permalink
docs: update fcm integration docs for v1 api
Browse files Browse the repository at this point in the history 
Signed-off-by: Alessandro Yuichi Okimoto <[email protected]>
  • Loading branch information
@cre8ivejp
cre8ivejp committed Aug 26, 2024
1 parent 9f14c5b commit f97c873
Show file tree
Hide file tree
Showing 5 changed files with 182 additions and 31 deletions.
113 changes: 97 additions & 16 deletions docs/integration/pushes.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,22 +8,26 @@ import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
import CenteredImg from '@site/src/components/centered-img/CenteredImg';

Push notifications are utilized in Bucketeer to send silent updates to user applications through Google Firebase Cloud Messaging (FCM). **These silent notifications ensure that user applications are automatically updated in real time with the latest flag configurations**. This approach guarantees that user data remains current and allows for user-side actions upon receiving notifications.
The Push feature is designed to send silent notifications with normal priority to your applications through **Google Firebase Cloud Messaging (FCM)**.

To configure push notifications, access the **Settings** in the left dashboard menu and navigate to the **Pushes** tab. Here, you will find a list of previously created Pushes and the option to create new ones using the **+ Add** button.
These silent notifications let your applications know when a flag changes in real time, so you can fetch the client cache and keep it always updated.

## Create a Push

When creating a new Push, you need to provide the following information:
To create a push notification, access the **Settings** menu on the left sidebar, navigate to the **Pushes** tab, and click on the **+ Add** button.

- **Name**: This identifies the push. Bucketeer recommends using descriptive names.
- **Firebase Cloud Messaging API Key**: This key identifies the desired group of users who will receive the notification.
- **Firebase Cloud Messaging Service Account**: This allows the Bucketeer to request the OAuth Access Token, which is needed to send notifications.
- **Tags**: Add tags related to the flags you wish to monitor. Upon updating or modifying a flag with the provided tag, the push notification will be triggered. You can select one or multiple tags to trigger the push notification.

:::info Tag selection
You can include multiple tags while creating a push. However, for larger user groups requiring numerous notifications, there might be a time delay or potential server overload on FCM.

Bucketeer's team suggests employing distinct FCM API Keys for each user group and associating specific tags with each group. This strategy minimizes the number of notifications after each flag modification.
Bucketeer's team suggests using distinct FCM service accounts for each user group and associating specific tags with each group. This strategy minimizes the number of notifications to be sent when a flag changes.
:::

:::info FCM Service Account
Please be aware that you can only create one Push using the same FCM service account.
:::

<CenteredImg
Expand All @@ -33,30 +37,56 @@ Bucketeer's team suggests employing distinct FCM API Keys for each user group an
borderWidth="1px"
/>

After defining the Name, Firebase Cloud Messaging API Key, and Tags, click **Submit** to create the push.
After defining the Name, FCM Service Account, and the Tags, click on **Submit** to create the push.

## Push notifications restrictions

Push notifications function is contingent on end-user configurations to operate effectively. When end-users install applications on their devices, such as iPhones, they are prompted to grant authorization for the application to use notifications. If users authorize the application for notifications, push notifications will function as intended. On the other hand, push notifications will not operate on their applications if users do not grant authorization. Refer to the flowchart below for an overview of the push notification process.
Push notifications function is contingent on end-user configurations to operate effectively. When end-users install applications on their devices, such as iPhones, they are prompted to grant authorization for the application to use notifications.

If users grant the notification permission, the FCM integration will work as intended. Refer to the flowchart below for an overview of the push notification process.

<CenteredImg
imgURL="img/integration/pushes/push_flow.svg"
alt="Create push"
wSize="550px"
/>

:::info Auto updates
Even if users disable notifications, their system will automatically update every ten minutes.
:::info Auto cache updates
Even if the users turn off the notifications, the client SDK will continue polling the latest cache from the server in the background.
:::

## Update user evaluation in real time

To leverage push notifications, implement a function in your application. This function will receive notifications from FCM and verify if `bucketeer_feature_flag_updated` is `true`. In such cases, update flag configurations using the `fetchEvaluations` function. Below are code examples of this function. For further details, consult the **Updating user evaluations in real-time** section on [SDK](/sdk) documentation.
When using the FCM integration, your applications must subscribe to Bucketeer's topic, so they can receive notifications.

The topic varies depending on the feature flag **tag**.<br />
E.g: **bucketeer-\<YOUR_FEATURE_FLAG_TAG\>**

Bucketeer will send the notification including the data **\{"bucketeer_feature_flag_updated":"true"\}**, so you can check if you need to fetch the client cache.

:::info Subscription Topic
The tag in the topic is the same tag used when initializing the client SDK.<br />
If you have a flag using the `android` tag, the topic will be **bucketeer-android**.
:::

<Tabs groupId="integrate-buckteer-platform">
<TabItem value="kt" label="Kotlin">

```kotlin showLineNumbers
// In order to receive notifications you must subscribe to the topic
private fun subscribeToTopic() {
val tag = "android" // The same tag used when initializing the client SDK
Firebase.messaging
.subscribeToTopic("bucketeer-$tag")
.addOnCompleteListener { task ->
var msg = "Subscribed successfully"
if (!task.isSuccessful) {
msg = "Failed to subscribe"
}
Log.d(TAG, msg)
}
}

override fun onMessageReceived(remoteMessage: RemoteMessage?) {
remoteMessage?.data?.also { data ->
val isFeatureFlagUpdated = data["bucketeer_feature_flag_updated"]
Expand All @@ -82,16 +112,23 @@ override fun onMessageReceived(remoteMessage: RemoteMessage?) {
```

</TabItem>
<TabItem value="dart" label="Dart">

```dart showLineNumbers
// TODO
```

</TabItem>
<TabItem value="swift" label="Swift">

```swift showLineNumbers
// In order to receive notifications you must subscribe to the topic
func subscribeToTopic() {
let tag = "ios" // The same tag used when initializing the client SDK
let topic = "bucketeer-\(tag)"
Messaging.messaging().subscribe(toTopic: topic) { error in
if let error = error {
print("Failed to subscribed to \(topic) topic. Error: \(error)")
} else {
print("Subscribed successfully to \(topic) topic")
}
}
}

// Receiving notification in background
func application(
_ application: UIApplication,
Expand All @@ -112,4 +149,48 @@ func application(
```

</TabItem>

<TabItem value="dart" label="Dart">

```dart showLineNumbers
/// In order to receive notifications you must subscribe to the topic
void subscribeToTopic() {
String tag = "flutter";
String topic = "bucketeer-$tag";
FirebaseMessaging.instance.subscribeToTopic(topic).then((_) {
debugPrint("Subscribed successfully to $topic topic");
}).catchError((error) {
debugPrint("Failed to subscribed to $topic topic. Error: $error");
});
}
FirebaseMessaging.onMessage.listen((RemoteMessage message) async {
final isFeatureFlagUpdated = message.data["bucketeer_feature_flag_updated"]
if (isFeatureFlagUpdated) {
int timeout = 1000;
const client = BKTClient.instance;
final result = await client.fetchEvaluations(timeoutMillis: timeout);
if (result.isSuccess) {
final showNewFeature = await client
.boolVariation("YOUR_FEATURE_FLAG_ID", defaultValue: false);
if (showNewFeature) {
/// The Application code to show the new feature
} else {
/// The code to run if the feature is off
}
} else {
/// Handle the error when the cache is not updated
if (result.asFailure.exception is BKTTimeoutException) {
/// Handle timeout error
} else {
/// Anything else
}
}
}
});
```

</TabItem>

</Tabs>
34 changes: 29 additions & 5 deletions docs/sdk/client-side/android/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -353,14 +353,24 @@ You don't need to call this method manually in regular use because the SDK is po

### Updating user evaluations in real-time

The Bucketeer SDK supports FCM ([Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging)).<br />
Every time you change a feature flag on the admin console, Bucketeer will send notifications using the FCM API to notify the client so that you can update the evaluations in real-time.
Bucketeer SDK supports FCM ([Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging)).<br />
Every time you change a feature flag on the admin console, Bucketeer will send a silent notification using the FCM V1 API to notify the client so that you can update the evaluations in real-time.

:::note
:::info Before using
1. You need to register your FCM Service Account on the admin console. Check the [Pushes](/integration/pushes) section to learn how to do it.
2. This feature may not work if the end-user has the notification disabled.
:::

:::info Subscription Topic
When using the FCM integration, your applications must subscribe to Bucketeer's topic, so they can receive notifications.<br />

The topic varies depending on the feature flag tag.<br />
E.g.: **bucketeer-\<YOUR_FEATURE_FLAG_TAG\>**

1. You need to register your FCM API Key on the admin console. Check the [Pushes](/integration/pushes) section to learn how to do it.
2. This feature may not work if the user has the notification disabled.
The tag in the topic is the same tag used when initializing the client SDK.<br />
If you have a flag using the `android` tag, the topic will be **bucketeer-android**.

**Please be aware that the tag is case-sensitive.**
:::

Assuming you already have the FCM implementation in your application.
Expand All @@ -369,6 +379,20 @@ Assuming you already have the FCM implementation in your application.
<TabItem value="kt" label="Kotlin">

```kotlin showLineNumbers
// In order to receive notifications you must subscribe to the topic
private fun subscribeToTopic() {
val tag = getTag() // The same tag used when initializing the client SDK
Firebase.messaging
.subscribeToTopic("bucketeer-$tag")
.addOnCompleteListener { task ->
var msg = "Subscribed successfully"
if (!task.isSuccessful) {
msg = "Failed to subscribe"
}
Log.d(TAG, msg)
}
}

override fun onMessageReceived(remoteMessage: RemoteMessage?) {
remoteMessage?.data?.also { data ->
val isFeatureFlagUpdated = data["bucketeer_feature_flag_updated"]
Expand Down
32 changes: 27 additions & 5 deletions docs/sdk/client-side/flutter/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -349,14 +349,24 @@ You don't need to call this method manually in regular use because the SDK is po

### Updating user evaluations in real-time

The Bucketeer SDK supports FCM ([Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging)).<br />
Every time you change a feature flag on the admin console, Bucketeer will send notifications using the FCM API to notify the client so that you can update the evaluations in real-time.
Bucketeer SDK supports FCM ([Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging)).<br />
Every time you change a feature flag on the admin console, Bucketeer will send a silent notification using the FCM V1 API to notify the client so that you can update the evaluations in real-time.

:::note
:::info Before using
1. You need to register your FCM Service Account on the admin console. Check the [Pushes](/integration/pushes) section to learn how to do it.
2. This feature may not work if the end-user has the notification disabled.
:::

:::info Subscription Topic
When using the FCM integration, your applications must subscribe to Bucketeer's topic, so they can receive notifications.<br />

1. You need to register your FCM API Key on the admin console. Check the [Pushes](/integration/pushes) section to learn how to do it.
2. This feature may not work if the user has the notification disabled.
The topic varies depending on the feature flag tag.<br />
E.g.: **bucketeer-\<YOUR_FEATURE_FLAG_TAG\>**

The tag in the topic is the same tag used when initializing the client SDK.<br />
If you have a flag using the `flutter` tag, the topic will be **bucketeer-flutter**.

**Please be aware that the tag is case-sensitive.**
:::

Assuming you already have the FCM implementation in your application.
Expand All @@ -365,6 +375,18 @@ Assuming you already have the FCM implementation in your application.
<TabItem value="dart" label="Dart">

```dart showLineNumbers
/// In order to receive notifications you must subscribe to the topic
void subscribeToTopic() {
String tag = "flutter";
String topic = "bucketeer-$tag";
FirebaseMessaging.instance.subscribeToTopic(topic).then((_) {
debugPrint("Subscribed successfully to $topic topic");
}).catchError((error) {
debugPrint("Failed to subscribed to $topic topic. Error: $error");
});
}
FirebaseMessaging.onMessage.listen((RemoteMessage message) async {
final isFeatureFlagUpdated = message.data["bucketeer_feature_flag_updated"]
if (isFeatureFlagUpdated) {
Expand Down
34 changes: 29 additions & 5 deletions docs/sdk/client-side/ios/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -392,14 +392,24 @@ You don't need to call this method manually in regular use because the SDK is po

### Updating user evaluations in real-time

The Bucketeer SDK supports FCM ([Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging)).<br />
Every time you change a feature flag on the admin console, Bucketeer will send notifications using the FCM API to notify the client so that you can update the evaluations in real-time.
Bucketeer SDK supports FCM ([Firebase Cloud Messaging](https://firebase.google.com/docs/cloud-messaging)).<br />
Every time you change a feature flag on the admin console, Bucketeer will send a silent notification using the FCM V1 API to notify the client so that you can update the evaluations in real-time.

:::note
:::info Before using
1. You need to register your FCM Service Account on the admin console. Check the [Pushes](/integration/pushes) section to learn how to do it.
2. This feature may not work if the end-user has the notification disabled.
:::

:::info Subscription Topic
When using the FCM integration, your applications must subscribe to Bucketeer's topic, so they can receive notifications.<br />

The topic varies depending on the feature flag tag.<br />
E.g.: **bucketeer-\<YOUR_FEATURE_FLAG_TAG\>**

1. You need to register your FCM API Key on the admin console. Check the [Pushes](/integration/pushes) section to learn how to do it.
2. This feature may not work if the user has the notification disabled.
The tag in the topic is the same tag used when initializing the client SDK.<br />
If you have a flag using the `ios` tag, the topic will be **bucketeer-ios**.

**Please be aware that the tag is case-sensitive.**
:::

Assuming you already have the FCM implementation in your application, the following example shows how to handle silent push notifications.
Expand All @@ -408,6 +418,20 @@ Assuming you already have the FCM implementation in your application, the follow
<TabItem value="swift" label="Swift">

```swift showLineNumbers
```swift showLineNumbers
// In order to receive notifications you must subscribe to the topic
func subscribeToTopic() {
let tag = "ios" // The same tag used when initializing the client SDK
let topic = "bucketeer-\(tag)"
Messaging.messaging().subscribe(toTopic: topic) { error in
if let error = error {
print("Failed to subscribed to \(topic) topic. Error: \(error)")
} else {
print("Subscribed successfully to \(topic) topic")
}
}
}

// Receiving notification in background
func application(
_ application: UIApplication,
Expand Down
Binary file modified static/img/integration/pushes/create-push.png
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.

0 comments on commit f97c873

Please sign in to comment.