# Integration Brief Template

A reusable hand-off template for consultants and developers. One brief per app per engagement — the consultant fills in the `{{PLACEHOLDER}}` fields, sends it to the developer, and both sides sign off when the acceptance test in §5 passes.

!!! tip "How to use this page"
    [Download this template](/downloads/airlock-integration-brief-template.md) and fill in the `{{PLACEHOLDER}}` fields.

---

# Airlock Integration Brief — {{CLIENT_NAME}} / {{APP_NAME}}

| Field | Value |
|---|---|
| Engagement | {{ENGAGEMENT_NAME}} |
| Consultant | {{CONSULTANT_NAME}} <{{CONSULTANT_EMAIL}}> |
| Developer contact | {{DEV_CONTACT_NAME}} <{{DEV_CONTACT_EMAIL}}> |
| Target platforms | iOS / Android / both |
| Airlock version | `{{AIRLOCK_VERSION}}` (e.g. `0.3.16`) |
| Brief issued | {{YYYY-MM-DD}} |
| Go-live target | {{YYYY-MM-DD}} |

## 1. What Airlock does in this app

Airlock is an [Adobe Launch](https://experienceleague.adobe.com/en/docs/experience-platform/tags) extension that runs on-device, intercepting every analytics event between `MobileCore.track*()` and Adobe's collection servers. It applies JavaScript rules authored in Launch — enriching, mutating, suppressing, or passing through events without an app rebuild.

**For this engagement, Airlock will be configured to:**

- {{BUSINESS_OUTCOME_1}}
- {{BUSINESS_OUTCOME_2}}
- {{BUSINESS_OUTCOME_3}}

The developer integrates the SDK once. All future rule changes ship over-the-air through Adobe Launch and require no app release.

## 2. Adobe Launch configuration

| Field | Value |
|---|---|
| Adobe org | {{ADOBE_ORG_NAME}} (`{{ADOBE_ORG_ID}}@AdobeOrg`) |
| Launch property name | {{LAUNCH_PROPERTY_NAME}} |
| Launch property ID | `{{LAUNCH_PROPERTY_ID}}` |
| Dev environment ID | `{{LAUNCH_DEV_APP_ID}}` |
| Stage environment ID | `{{LAUNCH_STAGE_APP_ID}}` |
| Prod environment ID | `{{LAUNCH_PROD_APP_ID}}` |

These IDs go into `MobileCore.configureWithAppId(...)` (see §4).

## 3. SDK dependencies

These must be installed and registered **in addition to** Airlock. Airlock requires AEP Core 5.0+ on iOS and 3.0+ on Android.

| Extension | iOS | Android | Why |
|---|---|---|---|
| AEP Core | `AEPCore` ≥ 5.0 | `com.adobe.marketing.mobile:core:3.+` | Required — event hub |
| AEP Identity | `AEPIdentity` ≥ 5.0 | `com.adobe.marketing.mobile:identity:3.+` | Required — ECID resolution |
| AEP Lifecycle | `AEPLifecycle` ≥ 5.0 | `com.adobe.marketing.mobile:lifecycle:3.+` | Recommended — session metrics |
| AEP Analytics | `AEPAnalytics` ≥ 5.0 | `com.adobe.marketing.mobile:analytics:3.+` | Required — actually sends the hit |
| AEP Assurance | `AEPAssurance` ≥ 5.0 | `com.adobe.marketing.mobile:assurance:3.+` | Required for acceptance test |
| **Airlock** | `Airlock` `{{AIRLOCK_VERSION}}` | `com.maxisdigital:airlock:{{AIRLOCK_VERSION}}` (via JitPack for v0.x) | The extension itself |

## 4. Integration steps

### 4a. iOS

**Add the package** in Xcode → File → Add Packages…:

```
https://github.com/maxisdigital/airlock-ios  → exact version {{AIRLOCK_VERSION}}
```

**Register at app launch.** In `AppDelegate.swift` (or your `@main` `App` init):

```swift
import AEPCore
import AEPIdentity
import AEPLifecycle
import AEPAnalytics
import AEPAssurance
import Airlock

func application(_ application: UIApplication,
                 didFinishLaunchingWithOptions launchOptions:
                 [UIApplication.LaunchOptionsKey: Any]?) -> Bool {

    MobileCore.setLogLevel(.debug)  // Remove for production
    MobileCore.registerExtensions([
        Identity.self,
        Lifecycle.self,
        Analytics.self,
        Assurance.self,
        Airlock.self,
    ]) {
        MobileCore.configureWith(appId: "{{LAUNCH_DEV_APP_ID}}")
        MobileCore.lifecycleStart(additionalContextData: nil)
    }
    return true
}
```

**Deep link** (for Assurance sessions). Add to `Info.plist`:

```xml
<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array><string>{{ASSURANCE_DEEP_LINK_SCHEME}}</string></array>
  </dict>
</array>
```

Forward the URL in `SceneDelegate`:

```swift
func scene(_ scene: UIScene, openURLContexts URLContexts: Set<UIOpenURLContext>) {
    URLContexts.forEach { Assurance.startSession(url: $0.url) }
}
```

### 4b. Android

**Add to `app/build.gradle.kts`** (root `settings.gradle.kts` must declare JitPack as a repository for v0.x):

```kotlin
// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://jitpack.io") }
    }
}
```

```kotlin
// app/build.gradle.kts
dependencies {
    implementation("com.adobe.marketing.mobile:core:3.+")
    implementation("com.adobe.marketing.mobile:identity:3.+")
    implementation("com.adobe.marketing.mobile:lifecycle:3.+")
    implementation("com.adobe.marketing.mobile:analytics:3.+")
    implementation("com.adobe.marketing.mobile:assurance:3.+")
    implementation("com.github.maxisdigital:airlock-android:{{AIRLOCK_VERSION}}")
}
```

**Register in `Application.onCreate()`:**

```kotlin
import com.adobe.marketing.mobile.*
import com.maxisdigital.airlock.Airlock

class MainApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        MobileCore.setApplication(this)
        MobileCore.setLogLevel(LoggingMode.DEBUG)  // Remove for production

        MobileCore.registerExtensions(
            listOf(
                Identity.EXTENSION,
                Lifecycle.EXTENSION,
                Analytics.EXTENSION,
                Assurance.EXTENSION,
                Airlock.EXTENSION,
            )
        ) {
            MobileCore.configureWithAppID("{{LAUNCH_DEV_APP_ID}}")
            MobileCore.lifecycleStart(null)
        }
    }
}
```

Declare it in the manifest: `android:name=".MainApplication"`.

**Assurance deep link** in `AndroidManifest.xml` (on the launcher activity):

```xml
<intent-filter>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="{{ASSURANCE_DEEP_LINK_SCHEME}}" />
</intent-filter>
```

Forward the URI in the activity's `onNewIntent`:

```kotlin
override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    intent.data?.let { Assurance.startSession(it.toString()) }
}
```

## 5. Acceptance test

The developer should consider integration complete when **all** of the following pass.

### 5a. Build & launch

- [ ] App builds clean against `{{AIRLOCK_VERSION}}` with no warnings about missing extensions
- [ ] App launches without crashing on a clean install

### 5b. Assurance session

- [ ] Consultant creates an Assurance session in Adobe Experience Platform
- [ ] Developer scans the QR / opens the deep link → app connects (green dot in Assurance UI)
- [ ] Assurance shows an `Airlock — (registered)` event in the event list

### 5c. Event flow

- [ ] App fires a `MobileCore.trackAction("test-event", nil)` (or in-app action)
- [ ] Assurance shows the original `generic.track / request.content` event
- [ ] Assurance shows a corresponding `Airlock Processed Track` event with `contextdata.airlock = "{{AIRLOCK_VERSION}}"` and `contextdata.airlock.status = "ok"`
- [ ] Adobe Analytics receives the enriched hit (visible in Assurance's "Network Requests" view)

### 5d. Rule execution (consultant validates)

- [ ] At least one configured rule from §1 fires and produces the expected modification on the outgoing hit

## 6. Boundaries — who owns what

**Developer owns:**

- App code, build configuration, dependency management
- SDK registration order and `configureWithAppId(...)` call
- Lifecycle / deep-link wiring
- Crash reporting, error tracking, anything outside the Adobe SDK stack

**Consultant owns:**

- Adobe Launch property — rules, data elements, extensions
- Airlock configuration (`airlock.enabled`, macros, lookup tables, accumulators, derived metrics)
- Rule JavaScript
- Adobe Analytics report suite configuration

!!! warning "Do not edit on the developer side"
    - The Airlock SDK source (it's a pinned dependency — bumping the version is fine, editing the source is not).
    - The Adobe Launch property unless co-ordinating with the consultant.

## 7. Support & escalation

| Need | Contact |
|---|---|
| Bug in Airlock SDK | File an issue: {{ISSUE_TRACKER_URL}} |
| Rule misbehaviour | Consultant: {{CONSULTANT_NAME}} <{{CONSULTANT_EMAIL}}> |
| Adobe SDK bug | [aepsdk-core-ios issues](https://github.com/adobe/aepsdk-core-ios/issues) / [aepsdk-core-android issues](https://github.com/adobe/aepsdk-core-android/issues) |
| Acceptance test failures | Walk through §5 with consultant on Assurance session |

## 8. Sign-off

- [ ] Developer has read this brief end-to-end
- [ ] §5 acceptance test passes against Dev environment
- [ ] §5 acceptance test passes against Stage environment
- [ ] §5 acceptance test passes against Prod environment

Developer: ______________________ Date: __________

Consultant: ______________________ Date: __________