# fbsamples/audience-network architecture

> Architecture diagram of the GitHub repository fbsamples/audience-network, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fbsamples/audience-network
- Repository: https://github.com/fbsamples/audience-network

## Overview

##### Project Type and Purpose
- This is an open-source repository containing sample applications that demonstrate how to integrate and use Facebook’s Audience Network SDK on Android and iOS, and how to interact with the Facebook Audience Reporting API via Python scripts.
- It is not a single monolithic system but rather three distinct sample modules (Android, iOS, Python) all exercising the same external service (Audience Network).

##### File Structure Analysis
- Top-level:
- .github/workflows/main.yml   → CI build & test
- README.md, CONTRIBUTING.md, LICENSE
- samples/android
- samples/ios
- samples/python
- Android samples: two variants (Java and Kotlin) each containing:
- build.gradle, Gradle wrapper, libs (AudienceNetwork.aar, DebugSettings.aar), source tree (Activities, Fragments, Adapters, Models)
- iOS samples: two variants (Objective-C AdUnitsSample and Swift FANSample) each containing:
- Xcode project files, Podfile, source (ViewControllers, Storyboards, Extensions, Utils)
- Python samples:
- reporting API scripts (adnw_requests.py, adnw_response.py, utility modules)

##### Key Insights from README
- Three sample categories: Android, iOS, Reporting API (Python)
- Purpose: demonstrate SDK initialization, ad unit loading/display, and reporting API usage
- External dependencies: Facebook Audience Network service endpoints and SDK binaries (AAR, CocoaPods)

##### Main Components
a. Sample Client Modules
- Android (Java), Android (Kotlin)
- iOS (Objective-C), iOS (Swift)
- Python reporting scripts
b. External Dependencies
- Facebook Audience Network SDK (distributed as AAR for Android, CocoaPods for iOS)
- Facebook Audience Network Ad Servers (ad request, ad response)
- Facebook Audience Reporting API endpoint
c. CI/CD
- GitHub Actions (build and smoke-test samples)

##### Relationships and Interactions
- Each sample client initializes the Audience Network SDK (via AudienceNetworkInitializeHelper on Android and Pod-provided APIs on iOS), then:
- Sends HTTP(S) ad requests to Audience Network servers
- Receives ad creative (JSON/XML/media)
- Renders ads in UI components (Fragments/Activities on Android, ViewControllers on iOS)
- Python scripts:
- Construct API calls to Reporting API
- Authenticate (via access tokens, parameters)
- Fetch and parse metrics data
- CI pipeline:
- Triggers builds of Android projects via Gradle and iOS via xcodebuild
- Runs linter/tests on Python scripts

##### Architectural Patterns and Principles
- Modular separation by platform
- Clear “Sample App → SDK → Remote Service” flow
- UI layer decoupled from SDK initialization and network logic
- Utility/helper modules centralize common tasks (logging, configuration, HTTP requests)

##### Essential Elements
- Annotations for protocols (Gradle, CocoaPods, pip), configuration files (Podfile, build.gradle) and CI triggers.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Left Column: Client Modules
    subgraph "Android Samples"
        direction TB
        subgraph "Java Sample"
            direction TB
            AJavaUI["UI Layer"]:::client
            AJavaSDK["SDK Integration Layer"]:::client
        end
        subgraph "Kotlin Sample"
            direction TB
            AKotlinUI["UI Layer"]:::client
            AKotlinSDK["SDK Integration Layer"]:::client
        end
    end

    subgraph "iOS Samples"
        direction TB
        subgraph "Objective-C Sample"
            direction TB
            iOSObjCUI["UI Layer"]:::client
            iOSObjCSDK["SDK Integration Layer"]:::client
        end
        subgraph "Swift Sample"
            direction TB
            iOSSwiftUI["UI Layer"]:::client
            iOSSwiftSDK["SDK Integration Layer"]:::client
        end
    end

    subgraph "Python Samples"
        direction TB
        PyScript["adnw_examples.py"]:::client
        PyHTTP["HTTP Client Utilities"]:::client
    end

    %% Middle Column: SDK & Libraries
    subgraph "SDK & Libraries"
        direction TB
        AARJava["AudienceNetwork.aar"]:::sdk
        DebugJava["DebugSettings.aar"]:::sdk
        AARKotlin["AudienceNetwork.aar"]:::sdk
        DebugKotlin["DebugSettings.aar"]:::sdk
        CocoaObjC["Podfile (Obj-C)"]:::sdk
        CocoaSwift["Podfile (Swift)"]:::sdk
        PyReq["adnw_requests.py"]:::sdk
        PyResp["adnw_response.py"]:::sdk
        PyUtils["adnw_utils.py"]:::sdk
    end

    %% Right Column: External Services
    subgraph "External Services"
        direction TB
        AdServer["Audience Network Ad Servers"]:::ext
        ReportingAPI["Audience Reporting API"]:::ext
    end

    %% Bottom: CI/CD
    CI["GitHub Actions CI Pipeline"]:::ci

    %% Relationships
    AJavaUI -->|"initializeSDK()"| AJavaSDK
    AJavaSDK -->|"loadAd(adUnitId)"| AARJava
    AARJava -->|"http request"| AdServer
    AdServer -->|"ad response"| AJavaSDK

    AKotlinUI -->|"initializeSDK()"| AKotlinSDK
    AKotlinSDK -->|"loadAd(adUnitId)"| AARKotlin
    AARKotlin -->|"http request"| AdServer
    AdServer -->|"ad response"| AKotlinSDK

    iOSObjCUI -->|"initializeSDK()"| iOSObjCSDK
    iOSObjCSDK -->|"loadAd(adUnitId)"| CocoaObjC
    CocoaObjC -->|"http request"| AdServer
    AdServer -->|"ad response"| iOSObjCSDK

    iOSSwiftUI -->|"initializeSDK()"| iOSSwiftSDK
    iOSSwiftSDK -->|"loadAd(adUnitId)"| CocoaSwift
    CocoaSwift -->|"http request"| AdServer
    AdServer -->|"ad response"| iOSSwiftSDK

    PyScript -->|"fetchReport(params)"| PyReq
    PyReq -->|"http request"| ReportingAPI
    ReportingAPI -->|"data response"| PyResp
    PyResp -->|"parsed data"| PyScript

    CI -->|"build/test"| AJavaUI
    CI -->|"build/test"| AKotlinUI
    CI -->|"build/test"| iOSObjCUI
    CI -->|"build/test"| iOSSwiftUI
    CI -->|"build/test"| PyScript

    %% Click Events
    click AJavaUI "https://github.com/fbsamples/audience-network/tree/main/samples/android/AdUnitsSample"
    click AJavaSDK "https://github.com/fbsamples/audience-network/blob/main/samples/android/AdUnitsSample/src/main/java/com/facebook/samples/AdUnitsSample/AudienceNetworkInitializeHelper.java"
    click AARJava "https://github.com/fbsamples/audience-network/blob/main/samples/android/AdUnitsSample/libs/AudienceNetwork.aar"
    click DebugJava "https://github.com/fbsamples/audience-network/blob/main/samples/android/AdUnitsSample/libs/DebugSettings.aar"

    click AKotlinUI "https://github.com/fbsamples/audience-network/tree/main/samples/android/KotlinAdUnitsSample"
    click AKotlinSDK "https://github.com/fbsamples/audience-network/blob/main/samples/android/KotlinAdUnitsSample/src/main/java/com/facebook/samples/adunitssamplekotlin/AudienceNetworkInitializeHelper.kt"
    click AARKotlin "https://github.com/fbsamples/audience-network/blob/main/samples/android/KotlinAdUnitsSample/libs/AudienceNetwork.aar"
    click DebugKotlin "https://github.com/fbsamples/audience-network/blob/main/samples/android/KotlinAdUnitsSample/libs/DebugSettings.aar"

    click iOSObjCUI "https://github.com/fbsamples/audience-network/tree/main/samples/ios/AdUnitsSample"
    click CocoaObjC "https://github.com/fbsamples/audience-network/tree/main/samples/ios/AdUnitsSample/Podfile"

    click iOSSwiftUI "https://github.com/fbsamples/audience-network/tree/main/samples/ios/FANSample"
    click CocoaSwift "https://github.com/fbsamples/audience-network/tree/main/samples/ios/FANSample/Podfile"

    click PyScript "https://github.com/fbsamples/audience-network/tree/main/samples/python/ReportingAPISamples"
    click PyReq "https://github.com/fbsamples/audience-network/blob/main/samples/python/ReportingAPISamples/adnw_requests.py"
    click PyResp "https://github.com/fbsamples/audience-network/blob/main/samples/python/ReportingAPISamples/adnw_response.py"
    click PyUtils "https://github.com/fbsamples/audience-network/blob/main/samples/python/ReportingAPISamples/adnw_utils.py"

    click CI "https://github.com/fbsamples/audience-network/blob/main/.github/workflows/main.yml"

    %% Styles
    classDef client fill:#D0E8FF,stroke:#1E90FF,stroke-width:1px
    classDef sdk fill:#E0FFE0,stroke:#28A745,stroke-width:1px
    classDef ext fill:#FFE4B5,stroke:#FF8C00,stroke-width:1px
    classDef ci fill:#F0F0F0,stroke:#A9A9A9,stroke-width:1px
```
