This document provides context for AI assistants and developers working on this project.

CeedAdsIOSSample serves as:

1. SDK Test Application: Primary test bed for validating ceed-ads-ios-sdk functionality
2. Integration Reference: Demonstrates best practices for SDK integration in SwiftUI apps
3. Demo Tool: Showcases ad delivery in conversational AI contexts to stakeholders

This sample app depends on the CeedAdsSDK Swift package. The SDK provides:

• CeedAdsSDK.initialize(appId:) - SDK initialization
• CeedAdsSDK.requestAd(conversationId:messageId:contextText:) - Ad request API
• ResolvedAd - Ad data model with format-specific configurations
• CeedAdsView - Unified view that auto-selects the appropriate format
• CeedAdsActionCardView - Traditional action card display
• CeedAdsLeadGenView - Email capture form
• CeedAdsStaticView - Banner-style display
• CeedAdsFollowupView - Engagement card with selectable options

Important: The SDK is a separate package. Changes to ad logic, ad formats, or API endpoints are made in the SDK repository, not here.

The app uses predefined scenarios (see ScenarioData.swift) to ensure consistent testing:

• Trigger: Keywords like "communicating", "another", "language"
• Purpose: Tests ad matching for language learning products
• Final context: "AI English conversation app"

• Trigger: Keyword "tech"
• Purpose: Tests ad matching for coding courses
• Final context: "AI coding course"

• Trigger: Default fallback (no English keywords detected)
• Purpose: Tests Japanese language ad matching
• Final context: Same as English but in Japanese

• Trigger: Keywords like "off", "places", "refreshing"
• Purpose: Tests ad matching for travel services
• Final context: "nice hotel"

• Trigger: "newsletter", "subscribe", "updates"
• Purpose: Tests lead_gen format with email capture
• Expected Ad Format: CeedAdsLeadGenView
• Events Tested: impression, submit

• Trigger: "event", "promotion", "deal"
• Purpose: Tests static format with banner display
• Expected Ad Format: CeedAdsStaticView
• Events Tested: impression, click

• Trigger: "feedback", "survey", "opinion"
• Purpose: Tests followup format with selectable options
• Expected Ad Format: CeedAdsFollowupView
• Events Tested: impression, optionTap

Rather than free-form conversation, we use scenarios because:

• Reproducibility: Same input always produces same conversation flow
• Testing: Easier to verify ad matching with known final context
• Demo reliability: Stakeholder demos work consistently

• Modern iOS development standard
• Better support for reactive UI updates
• Cleaner integration with async/await patterns

• Simpler than ObservableObject + @Published
• Better performance (fine-grained updates)
• Cleaner syntax

1. Define the scenario messages in ScenarioData.swift:

   let newScenario: [ScenarioMessage] = [
       ScenarioMessage(role: .user, text: "..."),
       ScenarioMessage(role: .ai, text: "..."),
       // ... alternating user/ai messages
   ]

2. Add to ScenarioType enum:

   enum ScenarioType: String {
       // ... existing cases
       case newScenario
   }

3. Add trigger keywords in scenarioDetectionKeywords:

   ScenarioKeyword(scenario: .newScenario, keywords: ["trigger", "words"]),

4. Register in scenarioTable:

   .newScenario: newScenario,

The ad content returned depends on the backend ad server configuration. To test different ads:

• Modify the contextText parameter in ad requests
• Ensure backend has ads configured for the test context
• Check Network debugging for request/response details

• Integrated new ad formats support using CeedAdsView (unified view)
• Added 3 new test scenarios: leadGen, staticAd, followup
• Updated ChatView to use unified view with callbacks
• Updated fallback message to include new scenario options

• Created initial README.md and CONTEXT.md documentation
• Project structure documented for future development

• Chat interface implemented with scenario-based conversations
• CeedAdsSDK integration completed
• Dark mode support added

• Initial project creation
• Basic SwiftUI app scaffold