From 67e6c83a5651e4b96dab98710f5857f1b0cb1c88 Mon Sep 17 00:00:00 2001 From: Nickolas Dimitrakas Date: Tue, 17 Feb 2026 15:18:50 -0500 Subject: [PATCH 1/6] generate readmes --- kits/README.md | 89 +++++++++++++++++++++++++++++++++++ kits/braze/braze-12/README.md | 53 ++++++++++++++++----- 2 files changed, 130 insertions(+), 12 deletions(-) create mode 100644 kits/README.md diff --git a/kits/README.md b/kits/README.md new file mode 100644 index 000000000..2f336a72a --- /dev/null +++ b/kits/README.md @@ -0,0 +1,89 @@ +# mParticle Apple SDK — Integration Kits + +This directory contains the source code for all mParticle integration kits (forwarders) that are part of the Apple SDK monorepo. + +## Monorepo Structure + +Each kit lives under a provider/version directory: + +``` +kits/ +└── / + └── -/ + ├── Package.swift # SPM manifest (this is what consumers resolve) + ├── CHANGELOG.md # Kit-specific release notes + ├── LICENSE + ├── README.md # Consumer-facing README (mirrors to the public repo) + ├── Sources/ # Kit implementation + ├── Tests/ # Unit tests + ├── Example/ # Sample apps (Swift + Obj-C) + └── *.xcodeproj # Xcode project for building the XCFramework +``` + +The version suffix (e.g., `braze-12`) corresponds to the **major version of the third-party SDK** that the kit integrates with, not the mParticle kit version itself. This allows multiple kit variants to coexist when a vendor ships breaking major releases (e.g., `braze-12`, `braze-13`). + +## Available Kits + +| Kit | Path | Mirror Repo | Third-Party SDK | +| -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| Braze 12 | `kits/braze/braze-12` | [`mparticle-apple-integration-braze-12`](https://github.com/mparticle-integrations/mparticle-apple-integration-braze-12) | [Braze Swift SDK 12.x](https://github.com/braze-inc/braze-swift-sdk) | + +## How Kits Are Released + +Kit releases are driven by the monorepo's CI pipeline and a single `VERSION` file at the repository root. + +### Release Flow + +1. **Version bump** — The `sdk-release-ecosystem-manual.yml` workflow creates a release PR that bumps the `VERSION` file and updates all kit podspecs and `Package.swift` dependencies. +2. **Merge to main** — When the release PR merges, `release-ecosystem-from-main.yml` triggers automatically. +3. **Per-kit mirror and release** — For each kit in the workflow matrix: + - The kit's XCFramework is built from its Xcode project. + - `git subtree split` extracts the kit directory into an isolated branch. + - The split branch is force-pushed to the kit's mirror repo under `mparticle-integrations/`. + - A GitHub release is created on the mirror repo with the XCFramework artifact and release notes from the kit's `CHANGELOG.md`. + +### Mirror Repos + +Each kit directory is mirrored to its own standalone repository under the [`mparticle-integrations`](https://github.com/mparticle-integrations) GitHub organization. These mirror repos are what consumers add as SPM or CocoaPods dependencies. **Do not commit directly to mirror repos** — all changes flow through this monorepo. + +``` +monorepo mirror repo +kits/braze/braze-12/ ──subtree split──> mparticle-integrations/mparticle-apple-integration-braze-12 +``` + +## Adding a New Kit + +1. Create the directory structure under `kits//-/`. +2. Add the kit source in `Sources/`, tests in `Tests/`, and example apps in `Example/`. +3. Create a `Package.swift` that depends on `mParticle/mparticle-apple-sdk` and the third-party SDK. +4. Add an Xcode project with a framework scheme for building the XCFramework. +5. Add a `CHANGELOG.md`, `LICENSE`, and consumer-facing `README.md`. +6. Register the kit in the workflow matrix in `.github/workflows/release-ecosystem-from-main.yml`. +7. Create the corresponding mirror repo under `mparticle-integrations/`. + +## Development + +### Building a Kit Locally + +Open the kit's Xcode project (e.g., `kits/braze/braze-12/mParticle-Braze.xcodeproj`) and build the framework scheme, or use SPM: + +```bash +cd kits/braze/braze-12 +swift build +``` + +### Running Kit Tests + +```bash +cd kits/braze/braze-12 +swift test +``` + +Or run tests from the Xcode project using Cmd+U. + +### Important Notes + +- **All kit changes happen here in the monorepo.** Never commit directly to mirror repos. +- **README files in kit directories are consumer-facing.** They get pushed to the mirror repo and are the first thing consumers see. Write them accordingly. +- **CHANGELOG.md entries are extracted during release** and used as GitHub release notes on the mirror repo. +- **Version alignment** — Kit versions are kept in sync with the core SDK version via the ecosystem release workflow. diff --git a/kits/braze/braze-12/README.md b/kits/braze/braze-12/README.md index 48b2e8b49..ca9db73a8 100644 --- a/kits/braze/braze-12/README.md +++ b/kits/braze/braze-12/README.md @@ -1,26 +1,55 @@ -# Braze (formerly Appboy) Kit Integration +# mParticle Braze Kit (Braze Swift SDK 12.x) -This repository contains the [Braze](https://www.braze.com) integration for the [mParticle Apple SDK](https://github.com/mParticle/mparticle-apple-sdk) using the latest [Braze Swift SDK](https://github.com/braze-inc/braze-swift-sdk/). +This is the [Braze](https://www.braze.com) integration for the [mParticle Apple SDK](https://github.com/mParticle/mparticle-apple-sdk), built against the [Braze Swift SDK 12.x](https://github.com/braze-inc/braze-swift-sdk). -## Adding the integration +## Source Code -1. Add the kit dependency using SPM: +This repository is a **read-only mirror**. The source code is maintained in the [mParticle Apple SDK monorepo](https://github.com/mParticle/mparticle-apple-sdk) under `kits/braze/braze-12/` and is automatically published here via CI. To contribute or report issues, please open issues and pull requests against the [monorepo](https://github.com/mParticle/mparticle-apple-sdk). - ```swift - github "mparticle-integrations/mparticle-apple-integration-braze-12" ~> 8.0 - ``` +## Installation -2. If using SPM, make sure to add the `-ObjC` flag to the target's `Other Linker Flags` setting in Xcode, according to the [Braze documentation](https://www.braze.com/docs/developer_guide/platform_integration_guides/ios/initial_sdk_setup/installation_methods/swift_package_manager#step-2-configuring-your-project). +### Swift Package Manager -3. Follow the mParticle iOS SDK [quick-start](https://github.com/mParticle/mparticle-apple-sdk), then rebuild and launch your app, and verify that you see `"Included kits: { Appboy }"` in your Xcode console +Add the package dependency in Xcode or in your `Package.swift`: -> (This requires your mParticle log level to be at least Debug) +```swift +.package( + url: "https://github.com/mparticle-integrations/mparticle-apple-integration-braze-12", + .upToNextMajor(from: "9.0.0") +) +``` -4. Reference mParticle's integration docs below to enable the integration. +Then add `mParticle-Braze` as a dependency of your target. + +> **Note:** Add the `-ObjC` flag to your target's **Other Linker Flags** build setting, per the [Braze documentation](https://www.braze.com/docs/developer_guide/platform_integration_guides/ios/initial_sdk_setup/installation_methods/swift_package_manager#step-2-configuring-your-project). + +### Verifying the Integration + +After installing, rebuild and launch your app. With the mParticle log level set to Debug or higher, you should see the following in your Xcode console: + +``` +Included kits: { Braze } +``` + +## Platform Support + +| Platform | Minimum Version | +| -------- | --------------- | +| iOS | 15.0 | +| tvOS | 15.0 | + +## Dependencies + +| Dependency | Version | +| ----------------------------------------------------------------------- | -------------------------------- | +| [mParticle Apple SDK](https://github.com/mParticle/mparticle-apple-sdk) | Aligned with kit release version | +| [Braze Swift SDK](https://github.com/braze-inc/braze-swift-sdk) | 12.0.0+ | ## Documentation -[Braze integration](https://docs.mparticle.com/integrations/braze/event/) +- [mParticle Braze Integration Guide](https://docs.mparticle.com/integrations/braze/event/) +- [mParticle Apple SDK Quick Start](https://github.com/mParticle/mparticle-apple-sdk) +- [Braze Swift SDK Documentation](https://www.braze.com/docs/) ## License From e846f16c98d2a7ed8b7d37c013a83aa85e490dc6 Mon Sep 17 00:00:00 2001 From: Nickolas Dimitrakas Date: Tue, 17 Feb 2026 15:42:38 -0500 Subject: [PATCH 2/6] Update README.md --- kits/README.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/kits/README.md b/kits/README.md index 2f336a72a..fff03909d 100644 --- a/kits/README.md +++ b/kits/README.md @@ -10,14 +10,14 @@ Each kit lives under a provider/version directory: kits/ └── / └── -/ - ├── Package.swift # SPM manifest (this is what consumers resolve) + ├── Package.swift # SPM manifest ├── CHANGELOG.md # Kit-specific release notes ├── LICENSE - ├── README.md # Consumer-facing README (mirrors to the public repo) + ├── README.md # Consumer-facing README ├── Sources/ # Kit implementation ├── Tests/ # Unit tests - ├── Example/ # Sample apps (Swift + Obj-C) - └── *.xcodeproj # Xcode project for building the XCFramework + ├── Example/ # Sample apps + └── *.xcodeproj # Developer project ``` The version suffix (e.g., `braze-12`) corresponds to the **major version of the third-party SDK** that the kit integrates with, not the mParticle kit version itself. This allows multiple kit variants to coexist when a vendor ships breaking major releases (e.g., `braze-12`, `braze-13`). From 7669370f0b30b3c03e11aa81377c07ba7cbe5496 Mon Sep 17 00:00:00 2001 From: Nickolas Dimitrakas Date: Tue, 17 Feb 2026 15:43:58 -0500 Subject: [PATCH 3/6] fix trunk push errors --- kits/README.md | 4 ++-- kits/braze/braze-12/README.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/kits/README.md b/kits/README.md index fff03909d..f96b0f372 100644 --- a/kits/README.md +++ b/kits/README.md @@ -6,7 +6,7 @@ This directory contains the source code for all mParticle integration kits (forw Each kit lives under a provider/version directory: -``` +```bash kits/ └── / └── -/ @@ -46,7 +46,7 @@ Kit releases are driven by the monorepo's CI pipeline and a single `VERSION` fil Each kit directory is mirrored to its own standalone repository under the [`mparticle-integrations`](https://github.com/mparticle-integrations) GitHub organization. These mirror repos are what consumers add as SPM or CocoaPods dependencies. **Do not commit directly to mirror repos** — all changes flow through this monorepo. -``` +```bash monorepo mirror repo kits/braze/braze-12/ ──subtree split──> mparticle-integrations/mparticle-apple-integration-braze-12 ``` diff --git a/kits/braze/braze-12/README.md b/kits/braze/braze-12/README.md index ca9db73a8..9f57ef176 100644 --- a/kits/braze/braze-12/README.md +++ b/kits/braze/braze-12/README.md @@ -27,7 +27,7 @@ Then add `mParticle-Braze` as a dependency of your target. After installing, rebuild and launch your app. With the mParticle log level set to Debug or higher, you should see the following in your Xcode console: -``` +```bash Included kits: { Braze } ``` From e8faa25852a0ae5056bc264346b7c48a0ea114a4 Mon Sep 17 00:00:00 2001 From: Nickolas Dimitrakas Date: Tue, 17 Feb 2026 17:42:37 -0500 Subject: [PATCH 4/6] add details for partner config of braze --- kits/braze/braze-12/README.md | 35 +++++++++++++++++++++++++++++++---- 1 file changed, 31 insertions(+), 4 deletions(-) diff --git a/kits/braze/braze-12/README.md b/kits/braze/braze-12/README.md index 9f57ef176..dfb054750 100644 --- a/kits/braze/braze-12/README.md +++ b/kits/braze/braze-12/README.md @@ -13,16 +13,43 @@ This repository is a **read-only mirror**. The source code is maintained in the Add the package dependency in Xcode or in your `Package.swift`: ```swift +let mParticleVersion: Version = "9.0.0" + .package( url: "https://github.com/mparticle-integrations/mparticle-apple-integration-braze-12", - .upToNextMajor(from: "9.0.0") -) + .upToNextMajor(from: mParticleVersion) +), +.package( + url: "https://github.com/mParticle/mparticle-apple-sdk", + .upToNextMajor(from: mParticleVersion) +), ``` Then add `mParticle-Braze` as a dependency of your target. > **Note:** Add the `-ObjC` flag to your target's **Other Linker Flags** build setting, per the [Braze documentation](https://www.braze.com/docs/developer_guide/platform_integration_guides/ios/initial_sdk_setup/installation_methods/swift_package_manager#step-2-configuring-your-project). +For iOS push-launch tracking, initialize Braze in `application(_:didFinishLaunchingWithOptions:)` **before** starting mParticle, then pass the instance to the kit: + +```swift +import BrazeKit +import mParticle_Braze + +let configuration = Braze.Configuration( + apiKey: "[YOUR_BRAZE_API_KEY]", + endpoint: "[YOUR_BRAZE_ENDPOINT]" +) +let braze = Braze(configuration: configuration) + +MPKitBraze.setBrazeInstance(braze) +MPKitBraze.setShouldDisableNotificationHandling(true) +// Start mParticle after this. +``` + +Complete setup details (including required push delegate methods) are in the mParticle docs: + +- [mParticle Braze iOS App Launch Tracking](https://docs.mparticle.com/integrations/braze/event/#ios-app-launch-tracking) + ### Verifying the Integration After installing, rebuild and launch your app. With the mParticle log level set to Debug or higher, you should see the following in your Xcode console: @@ -35,8 +62,8 @@ Included kits: { Braze } | Platform | Minimum Version | | -------- | --------------- | -| iOS | 15.0 | -| tvOS | 15.0 | +| iOS | 15.6 | +| tvOS | 15.6 | ## Dependencies From 4e53637b2b1f5dc41f512fcc07e5cd0ffd0a4276 Mon Sep 17 00:00:00 2001 From: Nickolas Dimitrakas Date: Tue, 17 Feb 2026 18:21:52 -0500 Subject: [PATCH 5/6] make readmes more customer focused --- kits/README.md | 90 +++++------------------------------ kits/braze/braze-12/README.md | 15 ++---- 2 files changed, 16 insertions(+), 89 deletions(-) diff --git a/kits/README.md b/kits/README.md index f96b0f372..ab51411bb 100644 --- a/kits/README.md +++ b/kits/README.md @@ -1,89 +1,25 @@ # mParticle Apple SDK — Integration Kits -This directory contains the source code for all mParticle integration kits (forwarders) that are part of the Apple SDK monorepo. +Kits forward events from the mParticle Apple SDK to partner services. To use a partner integration, add mParticle core plus the kit that matches the partner SDK major version you use. -## Monorepo Structure +## How to Choose a Kit -Each kit lives under a provider/version directory: +Kits are versioned by the partner SDK major: -```bash -kits/ -└── / - └── -/ - ├── Package.swift # SPM manifest - ├── CHANGELOG.md # Kit-specific release notes - ├── LICENSE - ├── README.md # Consumer-facing README - ├── Sources/ # Kit implementation - ├── Tests/ # Unit tests - ├── Example/ # Sample apps - └── *.xcodeproj # Developer project -``` +- `braze-12` → Braze Swift SDK 12.x -The version suffix (e.g., `braze-12`) corresponds to the **major version of the third-party SDK** that the kit integrates with, not the mParticle kit version itself. This allows multiple kit variants to coexist when a vendor ships breaking major releases (e.g., `braze-12`, `braze-13`). +Pick the kit that matches the partner SDK major you want in your app. -## Available Kits - -| Kit | Path | Mirror Repo | Third-Party SDK | -| -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | -| Braze 12 | `kits/braze/braze-12` | [`mparticle-apple-integration-braze-12`](https://github.com/mparticle-integrations/mparticle-apple-integration-braze-12) | [Braze Swift SDK 12.x](https://github.com/braze-inc/braze-swift-sdk) | - -## How Kits Are Released - -Kit releases are driven by the monorepo's CI pipeline and a single `VERSION` file at the repository root. - -### Release Flow - -1. **Version bump** — The `sdk-release-ecosystem-manual.yml` workflow creates a release PR that bumps the `VERSION` file and updates all kit podspecs and `Package.swift` dependencies. -2. **Merge to main** — When the release PR merges, `release-ecosystem-from-main.yml` triggers automatically. -3. **Per-kit mirror and release** — For each kit in the workflow matrix: - - The kit's XCFramework is built from its Xcode project. - - `git subtree split` extracts the kit directory into an isolated branch. - - The split branch is force-pushed to the kit's mirror repo under `mparticle-integrations/`. - - A GitHub release is created on the mirror repo with the XCFramework artifact and release notes from the kit's `CHANGELOG.md`. - -### Mirror Repos - -Each kit directory is mirrored to its own standalone repository under the [`mparticle-integrations`](https://github.com/mparticle-integrations) GitHub organization. These mirror repos are what consumers add as SPM or CocoaPods dependencies. **Do not commit directly to mirror repos** — all changes flow through this monorepo. +## Important Note (Monorepo Paths) -```bash -monorepo mirror repo -kits/braze/braze-12/ ──subtree split──> mparticle-integrations/mparticle-apple-integration-braze-12 -``` +The `kits//-/` paths are how kits are organized in this repository. For your app, use the **Standalone Repository** link below (or the kit's README) to install via your dependency manager. -## Adding a New Kit +## Setup Instructions -1. Create the directory structure under `kits//-/`. -2. Add the kit source in `Sources/`, tests in `Tests/`, and example apps in `Example/`. -3. Create a `Package.swift` that depends on `mParticle/mparticle-apple-sdk` and the third-party SDK. -4. Add an Xcode project with a framework scheme for building the XCFramework. -5. Add a `CHANGELOG.md`, `LICENSE`, and consumer-facing `README.md`. -6. Register the kit in the workflow matrix in `.github/workflows/release-ecosystem-from-main.yml`. -7. Create the corresponding mirror repo under `mparticle-integrations/`. +Each kit has its own README with installation and configuration steps. -## Development - -### Building a Kit Locally - -Open the kit's Xcode project (e.g., `kits/braze/braze-12/mParticle-Braze.xcodeproj`) and build the framework scheme, or use SPM: - -```bash -cd kits/braze/braze-12 -swift build -``` - -### Running Kit Tests - -```bash -cd kits/braze/braze-12 -swift test -``` - -Or run tests from the Xcode project using Cmd+U. - -### Important Notes +## Available Kits -- **All kit changes happen here in the monorepo.** Never commit directly to mirror repos. -- **README files in kit directories are consumer-facing.** They get pushed to the mirror repo and are the first thing consumers see. Write them accordingly. -- **CHANGELOG.md entries are extracted during release** and used as GitHub release notes on the mirror repo. -- **Version alignment** — Kit versions are kept in sync with the core SDK version via the ecosystem release workflow. +| Kit | Standalone Repository | Partner SDK | +| -------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------- | +| Braze 12 | [`mparticle-apple-integration-braze-12`](https://github.com/mparticle-integrations/mparticle-apple-integration-braze-12) | [Braze Swift SDK 12.x](https://github.com/braze-inc/braze-swift-sdk) | diff --git a/kits/braze/braze-12/README.md b/kits/braze/braze-12/README.md index dfb054750..e40893d32 100644 --- a/kits/braze/braze-12/README.md +++ b/kits/braze/braze-12/README.md @@ -2,12 +2,10 @@ This is the [Braze](https://www.braze.com) integration for the [mParticle Apple SDK](https://github.com/mParticle/mparticle-apple-sdk), built against the [Braze Swift SDK 12.x](https://github.com/braze-inc/braze-swift-sdk). -## Source Code - -This repository is a **read-only mirror**. The source code is maintained in the [mParticle Apple SDK monorepo](https://github.com/mParticle/mparticle-apple-sdk) under `kits/braze/braze-12/` and is automatically published here via CI. To contribute or report issues, please open issues and pull requests against the [monorepo](https://github.com/mParticle/mparticle-apple-sdk). - ## Installation +> **Viewing this from the monorepo?** Add the kit as a dependency from the [mparticle-integrations/mparticle-apple-integration-braze-12](https://github.com/mparticle-integrations/mparticle-apple-integration-braze-12) repository, not from the monorepo path. + ### Swift Package Manager Add the package dependency in Xcode or in your `Package.swift`: @@ -65,17 +63,10 @@ Included kits: { Braze } | iOS | 15.6 | | tvOS | 15.6 | -## Dependencies - -| Dependency | Version | -| ----------------------------------------------------------------------- | -------------------------------- | -| [mParticle Apple SDK](https://github.com/mParticle/mparticle-apple-sdk) | Aligned with kit release version | -| [Braze Swift SDK](https://github.com/braze-inc/braze-swift-sdk) | 12.0.0+ | - ## Documentation - [mParticle Braze Integration Guide](https://docs.mparticle.com/integrations/braze/event/) -- [mParticle Apple SDK Quick Start](https://github.com/mParticle/mparticle-apple-sdk) +- [mParticle iOS SDK Documentation](https://docs.mparticle.com/developers/client-sdks/ios/) - [Braze Swift SDK Documentation](https://www.braze.com/docs/) ## License From a50835f08b15d3baa929bc077b9d25c88691e1aa Mon Sep 17 00:00:00 2001 From: Nickolas Dimitrakas Date: Wed, 18 Feb 2026 12:23:11 -0500 Subject: [PATCH 6/6] address @jamesnrokt and @denischilik comments --- kits/braze/braze-12/README.md | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/kits/braze/braze-12/README.md b/kits/braze/braze-12/README.md index e40893d32..e3c17d27b 100644 --- a/kits/braze/braze-12/README.md +++ b/kits/braze/braze-12/README.md @@ -4,11 +4,10 @@ This is the [Braze](https://www.braze.com) integration for the [mParticle Apple ## Installation -> **Viewing this from the monorepo?** Add the kit as a dependency from the [mparticle-integrations/mparticle-apple-integration-braze-12](https://github.com/mparticle-integrations/mparticle-apple-integration-braze-12) repository, not from the monorepo path. - ### Swift Package Manager -Add the package dependency in Xcode or in your `Package.swift`: +Add the Braze kit package dependency in Xcode or in your `Package.swift`. +Swift Package Manager resolves the `mParticle` SDK automatically as a transitive dependency, so you do not need a separate `.package` entry for `mparticle-apple-sdk`. ```swift let mParticleVersion: Version = "9.0.0" @@ -17,10 +16,6 @@ let mParticleVersion: Version = "9.0.0" url: "https://github.com/mparticle-integrations/mparticle-apple-integration-braze-12", .upToNextMajor(from: mParticleVersion) ), -.package( - url: "https://github.com/mParticle/mparticle-apple-sdk", - .upToNextMajor(from: mParticleVersion) -), ``` Then add `mParticle-Braze` as a dependency of your target.