-
Notifications
You must be signed in to change notification settings - Fork 70
feat: Support Braze 43 and recommended eCommerce events #728
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.
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
Merged
Merged
Changes from all commits
Commits
Show all changes
13 commits
Select commit
Hold shift + click to select a range
339344a
feat: add braze-42 kit track with recommended eCommerce events
nickolas-dimitrakas 5f9ea24
fix(braze-42): correct example app applicationId to match push category
nickolas-dimitrakas 4c5cd90
fix(braze-42): avoid duplicating promoted keys in eCommerce metadata
nickolas-dimitrakas 04e7f90
fix(braze-42): address SonarCloud security findings on example manifests
nickolas-dimitrakas f06ae4f
chore(braze): rename braze-42 kit track directory to braze-43
BrandonStalnaker 8681bb9
feat(braze-43): map typed subtotalValue, tax, and shipping ecommerce …
BrandonStalnaker 234bc6f
address CR
BrandonStalnaker 1450dec
fix CI Tests
BrandonStalnaker e207c74
Merge branch 'main' into feat/braze-42-recommended-ecommerce
BrandonStalnaker caf65e2
update from appboy to braze
BrandonStalnaker 808e7a3
fix mapped attributes
BrandonStalnaker 80610cb
Merge branch 'main' into feat/braze-42-recommended-ecommerce
BrandonStalnaker 6149cfe
rename to Braze and add isolated publishing
BrandonStalnaker File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,98 @@ | ||
| # Braze (formerly Appboy) Kit Integration | ||
|
|
||
| This directory contains the [Braze](https://www.braze.com/) integration for the [mParticle Android SDK](https://github.com/mParticle/mparticle-android-sdk). | ||
|
|
||
| This `braze-43` kit track targets **Braze Android SDK 43.x** (`com.braze:android-sdk-ui:[43.0.0,44.0.0)`). Because Braze 43 requires Kotlin 2.2.x, this track is built standalone from the rest of the mParticle SDK (see the repository `ONBOARDING.md`). | ||
|
|
||
| ## Recommended eCommerce Events (opt-in) | ||
|
|
||
| Braze 42.3.0+ introduces [recommended eCommerce events](https://www.braze.com/docs/developer_guide/analytics/logging_ecommerce_events/#android); Braze 43.0.0 adds typed `subtotalValue`, `tax`, and `shipping` fields on cart, checkout, and order events. This kit can forward mParticle commerce events using that schema when the connection setting **`useEcommerceRecommendedEvents`** is enabled. When the setting is off (the default), commerce forwarding is unchanged and fully backward compatible. | ||
|
|
||
| When enabled, supported mParticle commerce actions map to Braze recommended events: | ||
|
|
||
| | mParticle commerce action | Braze recommended event | | ||
| | :------------------------ | :------------------------------------------------------------ | | ||
| | `add_to_cart` | `ecommerce.cart_updated` (action `add`) | | ||
| | `remove_from_cart` | `ecommerce.cart_updated` (action `remove`) | | ||
| | `checkout` | `ecommerce.checkout_started` | | ||
| | `view_detail` | `ecommerce.product_viewed` (one per product) | | ||
| | `purchase` | `ecommerce.order_placed` | | ||
| | `refund` | `ecommerce.order_refunded` (custom event; no typed Braze API) | | ||
|
|
||
| Requirements and behavior: | ||
|
|
||
| - **Minimum Braze Android SDK version: 43.0.0** (recommended eCommerce APIs plus typed `subtotalValue`/`tax`/`shipping`). Any commerce action not in the table above continues to use legacy forwarding. | ||
| - `TransactionAttributes.tax` / `shipping` map to Braze's typed `tax` / `shipping` fields. | ||
| - Cart/checkout IDs, subtotal, and product image/product URLs are resolved from kit attribute mappings (`cartIdAttribute`, `checkoutIdAttribute`, `subtotalValueAttribute`, `imageUrlAttribute`, `productUrlAttribute`). Each mapping's JSON `value` field is the mParticle attribute name to look up on the commerce event or product. Plain attribute-name strings are also accepted for local/test configs. | ||
| - Kit setting `source` is used as a direct Braze `source` value when set; otherwise `"android"`. | ||
| - `total_discounts` continues to be read from a commerce custom attribute named `total_discounts` (not kit-mapped). | ||
| - Attributes without a direct Braze equivalent (`affiliation`, product `brand`/`category`/`coupon_code`/`position`, etc.) are placed inside the event- or product-level `metadata` object, per Braze's strict recommended-event schema. Mapped attribute names that were promoted to typed fields are excluded from metadata. | ||
| - `cartId`/`checkoutId` fall back to the current mParticle session id and then a generated UUID when unmapped or missing. Image/product URLs are `null` when their mappings are unset or the mapped attribute is absent. | ||
|
|
||
| ## Example App | ||
|
|
||
| This repository contains an [example app](example) showing how to implement mParticle, Braze, and Firebase Cloud Messaging. The key changes you need to make to your app are below, and please also reference mParticle and Braze's documentation: | ||
|
|
||
| - [Instrumenting Push](https://docs.mparticle.com/developers/sdk/android/push-notifications) | ||
| - [Braze Documentation](https://docs.mparticle.com/integrations/braze/event) | ||
|
|
||
| ## 1. Adding the integration | ||
|
|
||
| [See a full build.gradle example here](https://github.com/mparticle-integrations/mparticle-android-integration-appboy/blob/master/example/build.gradle) | ||
|
|
||
| 1. Ensure `mavenCentral()` is included in your repositories (Braze is hosted on Maven Central; the legacy Appboy GitHub Pages Maven repo is not required): | ||
|
|
||
| ```groovy | ||
| repositories { | ||
| mavenCentral() | ||
| google() | ||
| ... | ||
| } | ||
| ``` | ||
|
|
||
| 2. Add the kit dependency to your app's `build.gradle`: | ||
|
|
||
| ```groovy | ||
| dependencies { | ||
| implementation 'com.mparticle:braze-43:6+' | ||
| } | ||
| ``` | ||
|
|
||
| ## 2. Registering for Push | ||
|
|
||
| mParticle's SDK takes care of registering for push notifications and passing tokens or instance IDs to the Braze SDK. [Follow the mParticle push notification documentation](https://docs.mparticle.com/developers/sdk/android/push-notifications#register-for-push-notifications) to instrument the SDK for push registration. You can skip over [this section of Braze's documentation](https://www.braze.com/docs/developer_guide/platform_integration_guides/android/push_notifications/integration/#registering-for-push). | ||
|
|
||
| ## 3. Displaying Push | ||
|
|
||
| [See a full example of an AndroidManifest.xml here](https://github.com/mparticle-integrations/mparticle-android-integration-appboy/blob/master/example/src/main/AndroidManifest.xml). | ||
|
|
||
| mParticle's SDK also takes care of capturing incoming push notifications and passing the resulting `Intent` to Braze's `BrazePushReceiver`. Follow the [mParticle push notification documentation](https://docs.mparticle.com/developers/sdk/android/push-notifications#display-push-notifications) to ensure you add the correct services and receivers to your app's AndroidManifest.xml. | ||
|
|
||
| ## 4. Reacting to Push and Deeplinking | ||
|
|
||
| There are a wide variety of implementation options available in Braze to deeplink a user when they tap a notification. There are **two specific requirements** to ensure automatic deeplinking works as intended. | ||
|
|
||
| - `BrazePushReceiver` | ||
|
|
||
| Whereas up until now you should have nothing Braze-specific in your `AndroidManifest.xml`, using Braze's automatic deeplinking does require you to add their `BrazePushReceiver`. Note that you do not need to specify any Intent filters (for example to receive push tokens, since mParticle takes care of that). You just need to add the following: | ||
|
|
||
| ```xml | ||
| <receiver android:name="com.braze.push.BrazePushReceiver" /> | ||
| ``` | ||
|
|
||
| - `braze.xml` | ||
|
|
||
| For automatic deep-linking, you need to add a boolean resource named `com_braze_handle_push_deep_links_automatically`. This can be in any resource file, or you can name it `braze.xml`: | ||
|
|
||
| ```xml | ||
| <?xml version="1.0" encoding="utf-8"?> | ||
| <resources> | ||
| <bool name="com_braze_handle_push_deep_links_automatically">true</bool> | ||
| </resources> | ||
| ``` | ||
|
|
||
| From here you should be able to successfully test push via Braze! Braze offers many client-side configurable options via xml resources and otherwise. Please see review the rest of [their documentation here](https://www.braze.com/docs/developer_guide/platform_integration_guides/android/push_notifications/integration/#step-3-add-deep-links) for more information. | ||
|
|
||
| ## License | ||
|
|
||
| [Apache License 2.0](http://www.apache.org/licenses/LICENSE-2.0) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,82 @@ | ||
| buildscript { | ||
| ext.kotlin_version = '2.2.20' | ||
| if (!project.hasProperty('version') || project.version.equals('unspecified')) { | ||
| project.version = '+' | ||
| } | ||
|
|
||
| repositories { | ||
| google() | ||
| mavenLocal() | ||
| mavenCentral() | ||
| } | ||
| dependencies { | ||
| classpath 'com.android.tools.build:gradle:8.1.4' | ||
| classpath 'com.mparticle:android-kit-plugin:' + project.version | ||
| classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version" | ||
| } | ||
| } | ||
|
|
||
| plugins { | ||
| id "org.sonarqube" version "3.5.0.2730" | ||
| id "org.jlleitschuh.gradle.ktlint" version "13.0.0" | ||
| } | ||
|
|
||
| sonarqube { | ||
| properties { | ||
| property "sonar.projectKey", "mparticle-android-integration-braze-43" | ||
| property "sonar.organization", "mparticle" | ||
| property "sonar.host.url", "https://sonarcloud.io" | ||
| } | ||
| } | ||
|
|
||
| apply plugin: 'org.jlleitschuh.gradle.ktlint' | ||
| apply plugin: 'kotlin-android' | ||
| apply plugin: 'com.mparticle.kit' | ||
|
|
||
| // Standalone builds use rootProject.name "android-braze-kit"; force the published | ||
| // Maven coordinate consumers expect (com.mparticle:braze-43). | ||
| if (extensions.findByName('mparticleMavenPublish') != null) { | ||
| mparticleMavenPublish { | ||
| artifactId.set('braze-43') | ||
| description.set('Braze 43 kit for the mParticle SDK') | ||
| } | ||
| } | ||
|
|
||
| android { | ||
| namespace 'com.mparticle.kits.braze43' | ||
| buildFeatures { | ||
| buildConfig = true | ||
| } | ||
| defaultConfig { | ||
| minSdkVersion 21 | ||
| } | ||
| lint { | ||
| // Workaround for lint internal crash | ||
| abortOnError false | ||
| // Ignore obsolete custom lint checks from older fragment library | ||
| disable 'ObsoleteLintCustomCheck' | ||
| } | ||
| compileOptions { | ||
| sourceCompatibility JavaVersion.VERSION_17 | ||
| targetCompatibility JavaVersion.VERSION_17 | ||
| } | ||
| kotlinOptions { | ||
| jvmTarget = '17' | ||
| } | ||
| testOptions { | ||
| unitTests.all { | ||
| jvmArgs += ['--add-opens', 'java.base/java.lang=ALL-UNNAMED'] | ||
| } | ||
| } | ||
| } | ||
|
|
||
| repositories { | ||
| mavenLocal() | ||
| mavenCentral() | ||
| } | ||
|
|
||
| dependencies { | ||
| compileOnly 'com.google.firebase:firebase-messaging:[10.2.1, )' | ||
| api 'com.braze:android-sdk-ui:[43.0.0,44.0.0)' | ||
| testImplementation files('libs/java-json.jar') | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,3 @@ | ||
| # Braze ships its own consumer ProGuard/R8 rules via android-sdk-ui. | ||
| # Because this kit declares Braze as an `api` dependency, those rules are | ||
| # applied transitively to consuming apps — no kit-level Braze keeps needed. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,65 @@ | ||
| /** | ||
| * | ||
| * Example app build.gradle for using mParticle + Braze + Firebase Cloud Messaging | ||
| * Please see the inline comments below. | ||
| * | ||
| */ | ||
|
|
||
|
|
||
| apply plugin: 'com.android.application' | ||
|
|
||
| android { | ||
| compileSdk 31 | ||
|
|
||
| defaultConfig { | ||
| applicationId "com.mparticle.kits.braze.example" | ||
| minSdk 16 | ||
| targetSdk 31 | ||
| versionCode 1 | ||
| versionName "1.0" | ||
|
|
||
| testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner" | ||
|
|
||
| } | ||
|
|
||
| buildTypes { | ||
| release { | ||
| minifyEnabled false | ||
| } | ||
| } | ||
| } | ||
|
|
||
| repositories { | ||
| mavenCentral() | ||
| google() | ||
| } | ||
|
|
||
| buildscript { | ||
| repositories { | ||
| //REQUIRED: com.google.gms:google-services requires both jCenter and Google's Maven :rollseyes: | ||
| mavenCentral() | ||
| google() | ||
| } | ||
| dependencies { | ||
| classpath 'com.google.gms:google-services:4.2.0' //REQUIRED for Firebase | ||
| } | ||
| } | ||
| dependencies { | ||
| implementation 'com.android.support:appcompat-v7:28.0.0' | ||
| implementation 'com.android.support:support-v4:28.0.0' | ||
| implementation 'com.android.support:support-media-compat:28.0.0' | ||
| implementation 'com.android.support.constraint:constraint-layout:1.1.3' | ||
|
|
||
| // REQUIRED: Add the Braze (formerly Appboy) kit here | ||
| // this will also pull in mParticle's Core SDK (com.mparticle:android-core) as a transitive dependency | ||
| implementation 'com.mparticle:braze-43:6+' | ||
|
|
||
| // REQUIRED for Firebase | ||
| implementation 'com.google.firebase:firebase-messaging:17.3.4' | ||
|
|
||
| // Not strictly required but strongly recommended so that mParticle and Braze can query for the Android Advertising ID | ||
| implementation 'com.google.android.gms:play-services-ads-identifier:16.0.0' | ||
|
|
||
| } | ||
|
|
||
| apply plugin: 'com.google.gms.google-services' //REQUIRED for Firebase |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,38 @@ | ||
| plugins { | ||
| id 'com.android.application' | ||
| id 'org.jetbrains.kotlin.android' | ||
| } | ||
|
|
||
| android { | ||
| namespace 'com.mparticle.kits.braze.braze43.example.kotlin' | ||
| compileSdk 35 | ||
|
|
||
| defaultConfig { | ||
| applicationId 'com.mparticle.kits.braze.braze43.example.kotlin' | ||
| minSdk 21 | ||
| targetSdk 35 | ||
| versionCode 1 | ||
| versionName '1.0' | ||
| } | ||
|
|
||
| compileOptions { | ||
| sourceCompatibility JavaVersion.VERSION_17 | ||
| targetCompatibility JavaVersion.VERSION_17 | ||
| } | ||
|
|
||
| kotlinOptions { | ||
| jvmTarget = '17' | ||
| } | ||
|
|
||
| buildTypes { | ||
| release { | ||
| minifyEnabled false | ||
| } | ||
| } | ||
| } | ||
|
|
||
| dependencies { | ||
| implementation project(':kits:braze:braze-43') | ||
| implementation 'androidx.appcompat:appcompat:1.6.1' | ||
| implementation 'com.google.android.material:material:1.11.0' | ||
| } |
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.