Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[SDK-4592] [BD-2646] Cordova - Add a comprehensive list of configurations for Android and iOS #6939

Merged
merged 10 commits into from
Mar 14, 2024
Merged

[SDK-4592] [BD-2646] Cordova - Add a comprehensive list of configurations for Android and iOS #6939

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
4675492
add configurations for Android page
vanessaland Feb 21, 2024
0a61754
add xml tag
vanessaland Feb 21, 2024
262548a
add iOS page
vanessaland Feb 21, 2024
4c64c59
remove custom endpoint
vanessaland Feb 21, 2024
b774352
Android/iOS page parity
vanessaland Feb 22, 2024
e45f918
capital title
vanessaland Feb 22, 2024
4c9ce4a
Tech writer overhaul
internetisaiah Mar 6, 2024
7f0237b
small edits
vanessaland Mar 13, 2024
a48be44
Final fixes + redirects
internetisaiah Mar 14, 2024
8a6b408
Merge branch 'develop' into SDK-4592
internetisaiah Mar 14, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions _docs/_developer_guide/platform_integration_guides/cordova/cordova_integration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,14 +20,14 @@ description: "This article covers initial SDK setup steps for iOS, Android, and
A custom API endpoint can be configured via the `config.xml`. For example, to use the EU endpoint, see the following:

#### Android
```
```xml
<platform name="android">
...
<preference name="com.braze.android_api_endpoint" value="sdk.fra-01.braze.eu" />
</platform>
```
#### iOS
```
```xml
<platform name="ios">
...
<preference name="com.braze.ios_api_endpoint" value="sdk.fra-01.braze.eu" />
Expand Down
82 changes: 74 additions & 8 deletions ...eveloper_guide/platform_integration_guides/cordova/initial_sdk_setup/android.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ description: "This article covers initial SDK setup steps for Android and FireOS
search_rank: 1
---

# Initial SDK Android setup
# Initial SDK Android Setup

> This reference article covers how to install the Braze Android SDK for Cordova.

Expand All @@ -29,7 +29,7 @@ cordova plugin add https://github.com/braze-inc/braze-cordova-sdk#master

## Configure the plugin

In your `config.xml`, add a `preference` element under the android `platform` element that contains your Braze API key with the name `com.braze.api_key`:
In your `config.xml`, add a `preference` element under the Android `platform` element that contains your Braze API key with the name `com.braze.api_key`:

```xml
<platform name="android">
Expand All @@ -41,32 +41,87 @@ In your `config.xml`, add a `preference` element under the android `platform` el

The Cordova Android SDK also allows for various other settings to be configured via the `config.xml` file:

| Method | Description |
| -----------------------------------------------| -------------------------------------------------------------------------------------------------------------------------------------------------------|
| `api_key` | Sets the API key for your application. |
| `android_api_endpoint` | Sets the [SDK endpoint]({{site.baseurl}}/api/basics/#endpoints) for your application. |
| `android_small_notification_icon` | Sets the notification small icon. |
| `android_large_notification_icon` | Sets the notification large icon. |
| `android_notification_accent_color` | Sets the notification accent color using a hexadecimal representation. |
| `android_default_session_timeout` | Sets the Braze session timeout for your application in seconds. Defaults to 10 seconds. |
| `android_handle_push_deep_links_automatically` | Sets whether the Braze SDK should automatically handle push deep links. |
| `android_log_level` | Sets the log level for your application. The default log level is 4 and will minimally log info. To enable verbose logging for debugging, use log level 2. |
| `firebase_cloud_messaging_registration_enabled`| Sets whether to use Firebase Cloud Messaging for push notifications. |
| `android_fcm_sender_id` | Sets the Firebase Cloud Messaging sender ID. |
| `enable_location_collection` | Sets whether the automatic location collection is enabled (if the user permits). |
| `geofences_enabled` | Sets whether geofences are enabled. |
| `android_disable_auto_session_tracking` | Sets whether to disable the Android Cordova plugin from automatically tracking sessions. |
| `sdk_authentication_enabled` | Sets whether to enable the [SDK Authentication](https://www.braze.com/docs/developer_guide/platform_wide/sdk_authentication#sdk-authentication) feature. |
| `trigger_action_minimum_time_interval_seconds` | Sets the minimum time interval in seconds between triggers. Defaults to 30 seconds. |
| `is_session_start_based_timeout_enabled` | Sets whether the session timeout behavior to be based either on session start or session end events. |
| `default_notification_channel_name` | Sets the user-facing name as seen via `NotificationChannel.getName` for the Braze default `NotificationChannel`. |
| `default_notification_channel_description` | Sets the user-facing description as seen via `NotificationChannel.getDescription` for the Braze default `NotificationChannel`. |
| `does_push_story_dismiss_on_click` | Sets whether a Push Story is automatically dismissed when clicked. |
| `is_fallback_firebase_messaging_service_enabled`| Sets whether the use of a fallback Firebase Cloud Messaging Service is enabled. |
| `fallback_firebase_messaging_service_classpath`| Sets the classpath for the fallback Firebase Cloud Messaging Service. |
| `is_content_cards_unread_visual_indicator_enabled`| Sets whether the Content Cards unread visual indication bar is enabled. |
| `is_firebase_messaging_service_on_new_token_registration_enabled`| Sets whether the Braze SDK will automatically register tokens in `com.google.firebase.messaging.FirebaseMessagingService.onNewToken`. |
| `is_push_deep_link_back_stack_activity_enabled` | Sets whether Braze will add an activity to the back stack when automatically following deep links for push. |
| `push_deep_link_back_stack_activity_class_name` | Sets the activity that Braze will add to the back stack when automatically following deep links for push. |
| `should_opt_in_when_push_authorized` | Sets if Braze should automatically opt-in the user when push is authorized. |

Example for setting extra configurations:

```xml
<platform name="android">
<preference name="com.braze.android_small_notification_icon" value="RESOURCE_ENTRY_NAME_FOR_ICON_DRAWABLE" />
<preference name="com.braze.android_large_notification_icon" value="RESOURCE_ENTRY_NAME_FOR_ICON_DRAWABLE" />
<preference name="com.braze.android_notification_accent_color" value="str_ACCENT_COLOR_INTEGER" />
<preference name="com.braze.android_default_session_timeout" value="str_SESSION_TIMEOUT_INTEGER" />
<preference name="com.braze.android_handle_push_deep_links_automatically" value="true"/"false" />
<preference name="com.braze.android_log_level" value=LOG_LEVEL_INTEGER />
<preference name="com.braze.android_log_level" value="str_LOG_LEVEL_INTEGER" />
<preference name="com.braze.firebase_cloud_messaging_registration_enabled" value="true"/"false" />
<preference name="com.braze.android_fcm_sender_id" value="str_YOUR_FCM_SENDER_ID" />
<preference name="com.braze.enable_location_collection" value="true"/"false" />
<preference name="com.braze.geofences_enabled" value="true"/"false" />
<preference name="com.braze.android_disable_auto_session_tracking" value="true"/"false" />
<preference name="com.braze.sdk_authentication_enabled" value="true"/"false" />
<preference name="com.braze.trigger_action_minimum_time_interval_seconds" value="str_MINIMUM_INTERVAL_INTEGER" />
<preference name="com.braze.is_session_start_based_timeout_enabled" value="false"/"true" />
<preference name="com.braze.default_notification_channel_name" value="DEFAULT_NAME" />
<preference name="com.braze.default_notification_channel_description" value="DEFAULT_DESCRIPTION" />
<preference name="com.braze.does_push_story_dismiss_on_click" value="true"/"false" />
<preference name="com.braze.is_fallback_firebase_messaging_service_enabled" value="true"/"false" />
<preference name="com.braze.fallback_firebase_messaging_service_classpath" value="FALLBACK_FIREBASE_MESSAGING_CLASSPATH" />
<preference name="com.braze.is_content_cards_unread_visual_indicator_enabled" value="true"/"false" />
<preference name="com.braze.is_firebase_messaging_service_on_new_token_registration_enabled" value="true"/"false" />
<preference name="com.braze.is_push_deep_link_back_stack_activity_enabled" value="true"/"false" />
<preference name="com.braze.push_deep_link_back_stack_activity_class_name" value="DEEPLINK_BACKSTACK_ACTIVITY_CLASS_NAME" />
<preference name="com.braze.should_opt_in_when_push_authorized" value="true"/"false" />
</platform>
```

See [Android Cordova plugin][2] for more details.

### Numerical preference example

Due to how the Cordova 8.0.0+ framework handles preferences, entirely numerical preferences like sender IDs must be prefixed with `str_` in order to be properly read by the SDK, like in the following example:
Due to how the Cordova 8.0.0+ framework handles preferences, entirely numerical preferences like sender IDs must be strings prefixed with `str_` in order to be properly read by the SDK, like in the following example:

```xml
<platform name="android">
<preference name="com.braze.firebase_cloud_messaging_registration_enabled" value="true" />
<preference name="com.braze.android_fcm_sender_id" value="str_64422926741" />
<preference name="com.braze.android_default_session_timeout" value="str_10" />
</platform>
```

### Boolean preference example

Boolean preferences are read by the SDK using `true` and `false` keywords as a string representation, like in the following example:

```xml
<platform name="android">
<preference name="com.braze.should_opt_in_when_push_authorized" value="true" />
<preference name="com.braze.is_session_start_based_timeout_enabled" value="false" />
</platform>
```

Expand Down Expand Up @@ -97,20 +152,31 @@ To enable location collection and Braze Geofences, use the [`geofence-branch`][3
</platform>
```

The geofence-branch can be added to your Cordova project with the following:
The `geofence-branch` can be added to your Cordova project with the following:

```
cordova plugin add https://github.com/braze-inc/braze-cordova-sdk#geofence-branch
```

See [Android Geofences][4] for more details.

### Delaying automatic session tracking

Set `<preference name="com.braze.android_disable_auto_session_tracking" value="true" />` in your `config.xml` to disable the Android Cordova plugin from automatically tracking sessions. To start tracking sessions, call `BrazePlugin.startSessionTracking()`. Note that this will not retroactively track sessions and will only start tracking sessions starting from the next `Activity.onStart()`.
To disable the Android Cordova plugin from automatically tracking sessions, set the following configuration preference in your `config.xml`:

```xml
<platform name="android">
<preference name="com.braze.android_disable_auto_session_tracking" value="true" />
</platform>
```

To start tracking sessions, call `BrazePlugin.startSessionTracking()`. Note that this will not retroactively track sessions and will only start tracking sessions starting from the next `Activity.onStart()`.

## Initial setup complete

Once the initial setup is complete, you can access your app's `BrazePlugin` JavaScript interface.
Once the initial setup is complete, you can access the `BrazePlugin` JavaScript interface in your app.

[1]: https://github.com/braze-inc/braze-cordova-sdk
[2]: https://github.com/braze-inc/braze-cordova-sdk/blob/master/src/android/BrazePlugin.kt
[3]: https://github.com/braze-inc/braze-cordova-sdk/tree/geofence-branch
[4]: {{site.baseurl}}/developer_guide/platform_integration_guides/android/advanced_use_cases/locations_and_geofences/
110 changes: 96 additions & 14 deletions ...s/_developer_guide/platform_integration_guides/cordova/initial_sdk_setup/ios.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,35 +38,105 @@ In your `config.xml`, add a `preference` element under the iOS `platform` elemen

Set up your applications to have the appropriate certificates for push, via the [iOS push documentation][2].

### Removing automatic push setup
## Setting extra configuration

The Cordova iOS SDK also allows for various other settings to be configured via the `config.xml` file:

| Method | Description |
| -----------------------------------------------| -------------------------------------------------------------------------------------------------------------------------------------------------------|
| `api_key` | Sets the API key for your application. |
| `ios_api_endpoint` | Sets the [SDK endpoint]({{site.baseurl}}/api/basics/#endpoints) for your application. |
| `ios_disable_automatic_push_registration` | Sets whether automatic push registration should be disabled. |
| `ios_disable_automatic_push_handling` | Sets whether automatic push handling should be disabled. |
| `ios_enable_idfa_automatic_collection` | Sets whether the Braze SDK should automatically collect the IDFA information. |
| `enable_location_collection` | Sets whether the automatic location collection is enabled (if the user permits). |
| `geofences_enabled` | Sets whether geofences are enabled. |
| `ios_session_timeout` | Sets the Braze session timeout for your application in seconds. Defaults to 10 seconds. |
| `sdk_authentication_enabled` | Sets whether to enable the [SDK Authentication](https://www.braze.com/docs/developer_guide/platform_wide/sdk_authentication#sdk-authentication) feature. |
| `display_foreground_push_notifications` | Sets whether push notifications should be displayed while the application is in the foreground. |
| `ios_disable_un_authorization_option_provisional` | Sets whether `UNAuthorizationOptionProvisional` should be disabled. |
| `trigger_action_minimum_time_interval_seconds` | Sets the minimum time interval in seconds between triggers. Defaults to 30 seconds. |
| `ios_push_app_group` | Sets the app group ID for iOS push extensions. |
| `ios_forward_universal_links` | Sets if the SDK should automatically recognize and forward universal links to the system methods. |
| `ios_log_level` | Sets the minimum logging level for `Braze.Configuration.Logger`. |
| `ios_use_uuid_as_device_id` | Sets if a randomly generated UUID should be used as the device ID. |
| `ios_flush_interval_seconds` | Sets the interval in seconds between automatic data flushes. Defaults to 10 seconds. |
| `ios_use_automatic_request_policy` | Sets whether the request policy for `Braze.Configuration.Api` should be automatic or manual. |
| `should_opt_in_when_push_authorized` | Sets if a user’s notification subscription state should automatically be set to `optedIn` when push permissions are authorized. |

Example for setting extra configurations:

If you want to turn off iOS automatic push registration, set the following configuration preferences:
```xml
<platform name="ios">
<preference name="com.braze.ios_disable_automatic_push_registration" value="NO"/"YES" />
<preference name="com.braze.ios_disable_automatic_push_handling" value="NO"/"YES" />
<preference name="com.braze.ios_enable_idfa_automatic_collection" value="YES"/"NO" />
<preference name="com.braze.enable_location_collection" value="NO"/"YES" />
<preference name="com.braze.geofences_enabled" value="NO"/"YES" />
<preference name="com.braze.ios_session_timeout" value="5" />
<preference name="com.braze.sdk_authentication_enabled" value="YES"/"NO" />
<preference name="com.braze.display_foreground_push_notifications" value="YES"/"NO" />
<preference name="com.braze.ios_disable_un_authorization_option_provisional" value="NO"/"YES" />
<preference name="com.braze.trigger_action_minimum_time_interval_seconds" value="30" />
<preference name="com.braze.ios_push_app_group" value="PUSH_APP_GROUP_ID" />
<preference name="com.braze.ios_forward_universal_links" value="YES"/"NO" />
<preference name="com.braze.ios_log_level" value="2" />
<preference name="com.braze.ios_use_uuid_as_device_id" value="YES"/"NO" />
<preference name="com.braze.ios_flush_interval_seconds" value="10" />
<preference name="com.braze.ios_use_automatic_request_policy" value="YES"/"NO" />
<preference name="com.braze.should_opt_in_when_push_authorized" value="YES"/"NO" />
</platform>
```

See [iOS Cordova plugin][3] for more details.

### Numerical preference example

Numerical preferences are read by the SDK as string representations, like in the following example:

```xml
<platform name="ios">
<preference name="com.braze.ios_disable_automatic_push_registration" value="YES" />
...
<preference name="com.braze.ios_flush_interval_seconds" value="10" />
<preference name="com.braze.ios_session_timeout" value="5" />
</platform>
```

### Optional IDFA collection
### Boolean preference example

To enable the automatic collection of the [iOS IDFA][3], set the following configuration preferences:
Boolean preferences are read by the SDK using `YES` and `NO` keywords as a string representation, like in the following example:

```xml
<platform name="ios">
<preference name="com.braze.ios_enable_idfa_automatic_collection" value="YES" />
<preference name="com.braze.should_opt_in_when_push_authorized" value="YES" />
<preference name="com.braze.ios_disable_automatic_push_handling" value="NO" />
</platform>
```

## Customized setup

This plugin can be forked and modified for custom implementations. Find the platform-specific native source code in the `/plugin/src` directory, the JavaScript interface in the `/plugin/www` directory, and the main configuration file at `/plugin`.

Users that check their platform directory into version control (enabling them to make permanent code edits there) will be able to further leverage Braze UI elements by calling them directly from their platform-specific project.

### Removing automatic push setup (iOS)

If you want to turn off iOS automatic push registration, set the following configuration preferences:

```xml
<platform name="ios">
<preference name="com.braze.ios_disable_automatic_push_registration" value="YES" />
...
</platform>
```

### Location collection and geofences

To enable location collection and Braze Geofences, use the `geofence-branch` instead of the default `master` branch. By default, the Braze SDK disables location collection and Braze Geofences. Additionally, use the following preferences configuration:
To enable location collection and Braze Geofences, use the [`geofence-branch`][4] instead of the default `master` branch. By default, the Braze SDK disables location collection and Braze Geofences. Additionally, use the following preferences configuration:

```xml
<platform name="ios">
<preference name="com.braze.enable_location_collection" value="true" />
<preference name="com.braze.geofences_enabled" value="true" />
<preference name="com.braze.enable_location_collection" value="YES" />
<preference name="com.braze.geofences_enabled" value="YES" />
</platform>
```

Expand All @@ -76,13 +146,25 @@ The `geofence-branch` can be added to your Cordova project with the following:
cordova plugin add https://github.com/braze-inc/braze-cordova-sdk#geofence-branch
```

See [iOS Geofences][4] for more details.
See [iOS Geofences][5] for more details.

### Optional IDFA collection

To enable the automatic collection of the [iOS IDFA][6], set the following configuration preference in your `config.xml`:

```xml
<platform name="ios">
<preference name="com.braze.ios_enable_idfa_automatic_collection" value="YES" />
</platform>
```

### Initial setup complete
## Initial setup complete

Once the initial setup is complete, you can access the `BrazePlugin` JavaScript interface in your app.

[1]: https://github.com/braze-inc/braze-cordova-sdk
[2]: {{site.baseurl}}/developer_guide/platform_integration_guides/swift/push_notifications/integration/
[3]: https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/set(identifierforadvertiser:)/
[4]: {{site.baseurl}}/developer_guide/platform_integration_guides/swift/advanced_use_cases/locations_and_geofences/
[3]: https://github.com/braze-inc/braze-cordova-sdk/blob/master/src/ios/BrazePlugin.m
[4]: https://github.com/braze-inc/braze-cordova-sdk/tree/geofence-branch
[5]: {{site.baseurl}}/developer_guide/platform_integration_guides/swift/advanced_use_cases/locations_and_geofences/
[6]: https://braze-inc.github.io/braze-swift-sdk/documentation/brazekit/braze/set(identifierforadvertiser:)/