[Feature] Unknown User Activation (#764)

Co-authored-by: hardikmashru <[email protected]>
Co-authored-by: Evan Greer <[email protected]>
Co-authored-by: Akshay Ayyanchira <[email protected]>
Co-authored-by: Megha <[email protected]>
Co-authored-by: hani <[email protected]>
Co-authored-by: Joao Dordio <[email protected]>
Co-authored-by: lokeshdud <[email protected]>
Co-authored-by: sumeruchat <[email protected]>

Author: 9 people

.github/workflows/build-and-test.yml

@@ -74,7 +74,8 @@ jobs:
               total_tests: 0,
               passed_tests: 0,
               failed_tests: 0,
-              success_rate: 0
+              success_rate: 0,
+              skipped_tests: 0
             };
             
             try {
@@ -92,17 +93,93 @@ jobs:
             } catch (error) {
               core.warning(`Error reading test summary: ${error.message}`);
             }
-
-             
-            // Extract just the main content from the HTML - removing the HTML tags
+            
+            // Clean and optimize HTML for GitHub Check Run API
             function stripHtml(html) {
-              // Simple regex to extract text content from HTML
+              if (!html) return '';
+              
               return html
-                .replace(/<h2>[\s\S]*?<\/h2>/gi, '')
+                // Remove problematic elements
+                .replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, '')
+                .replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, '')
+                // Clean up complex attributes but keep basic structure
+                .replace(/\s*(class|id|dir|data-[^=]*|role|aria-[^=]*|tabindex)="[^"]*"/gi, '')
+                .replace(/\s*(markdown-accessiblity-table|data-catalyst)="[^"]*"/gi, '')
+                // Remove GitHub-specific elements that don't render in Check Runs
+                .replace(/<g-emoji[^>]*>.*?<\/g-emoji>/gi, '⚠️')
+                .replace(/<clipboard-copy[\s\S]*?<\/clipboard-copy>/gi, '')
+                .replace(/<div class="zeroclipboard-container[\s\S]*?<\/div>/gi, '')
+                .replace(/<div class="snippet-clipboard-content[\s\S]*?<\/div>/gi, '')
+                // Clean up excessive whitespace
+                .replace(/\s+/g, ' ')
+                .replace(/>\s+</g, '><')
                 .trim();
             }
             
-            // Create the check with test results as summary and coverage as details
+            // Function to safely truncate content to fit byte limit
+            function truncateToByteLimit(text, maxBytes) {
+              if (!text) return '';
+              
+              // Convert to bytes to check actual size
+              const encoder = new TextEncoder();
+              let bytes = encoder.encode(text);
+              
+              if (bytes.length <= maxBytes) {
+                return text;
+              }
+              
+              // Binary search to find the maximum length that fits
+              let left = 0;
+              let right = text.length;
+              let result = '';
+              
+              while (left <= right) {
+                const mid = Math.floor((left + right) / 2);
+                const substring = text.substring(0, mid);
+                const substringBytes = encoder.encode(substring);
+                
+                if (substringBytes.length <= maxBytes) {
+                  result = substring;
+                  left = mid + 1;
+                } else {
+                  right = mid - 1;
+                }
+              }
+              
+              // Add truncation indicator if content was cut off
+              if (result.length < text.length) {
+                const truncateMsg = '\n\n... (truncated due to size limits)';
+                const truncateMsgBytes = encoder.encode(truncateMsg);
+                
+                if (encoder.encode(result).length + truncateMsgBytes.length <= maxBytes) {
+                  result += truncateMsg;
+                }
+              }
+              
+              return result;
+            }
+            
+            // Extract and clean content
+            const cleanTestReport = stripHtml(testReport);
+            const cleanCoverageReport = stripHtml(coverageReport);
+            
+            // Create concise summary focusing on key information
+            const summaryContent = `Test Results Summary:
+            • Total Tests: ${testStats.total_tests}
+            • Passed: ${testStats.passed_tests}
+            • Failed: ${testStats.failed_tests}
+            • Skipped: ${testStats.skipped_tests || 0}
+            • Success Rate: ${(testStats.success_rate || 0).toFixed(1)}%
+            
+            ${cleanTestReport}`;
+            
+            // Ensure summary fits within GitHub's 65535 byte limit (leaving some buffer)
+            const truncatedSummary = truncateToByteLimit(summaryContent, 65000);
+            
+            // Ensure coverage report fits within the text field limit
+            const truncatedCoverage = truncateToByteLimit(cleanCoverageReport, 65000);
+            
+            // Create the check with test results
             await github.rest.checks.create({
               owner: context.repo.owner,
               repo: context.repo.repo,
@@ -111,9 +188,9 @@ jobs:
               status: 'completed',
               conclusion: testStats.failed_tests > 0 ? 'failure' : 'success',
               output: {
-                title: `Tests: ${testStats.passed_tests}/${testStats.passed_tests + testStats.failed_tests} passed (${(testStats.success_rate).toFixed(1)}%) Skipped: ${testStats.skipped_tests}`,
-                summary: stripHtml(testReport.substring(0, 65000)),
-                text: stripHtml(coverageReport.substring(0, 65000))
+                title: `Tests: ${testStats.passed_tests}/${testStats.passed_tests + testStats.failed_tests} passed (${(testStats.success_rate || 0).toFixed(1)}%) Skipped: ${testStats.skipped_tests || 0}`,
+                summary: truncatedSummary,
+                text: truncatedCoverage
               }
             });
 

AGENT_README.md

@@ -0,0 +1,166 @@
+# AGENT README - Iterable Swift SDK
+
+## Project Overview
+This is the **Iterable Swift SDK** for iOS/macOS integration. The SDK provides:
+- Push notification handling
+- In-app messaging 
+- Event tracking
+- User management
+- Unknown user tracking
+
+## Key Architecture
+- **Core SDK**: `swift-sdk/` - Main SDK implementation
+- **Sample Apps**: `sample-apps/` - Example integrations
+- **Tests**: `tests/` - Unit tests, UI tests, and integration tests
+- **Notification Extension**: `notification-extension/` - Rich push support
+
+## Development Workflow
+
+### 🔨 Building the SDK
+```bash
+./agent_build.sh
+```
+- Validates compilation on iOS Simulator
+- Shows build errors with context
+- Requires macOS with Xcode
+
+### Listing All Available Tests
+
+# List all available test suites
+```bash
+./agent_test.sh --list
+```
+
+### 🧪 Running Tests  
+```bash
+# Run all tests
+./agent_test.sh
+
+# Run specific test suite
+./agent_test.sh IterableApiCriteriaFetchTests
+
+# Run specific unit test (dot notation - recommended)
+./agent_test.sh "IterableApiCriteriaFetchTests.testForegroundCriteriaFetchWhenConditionsMet"
+
+# Run any specific test with path 
+./agent_test.sh "unit-tests/IterableApiCriteriaFetchTests/testForegroundCriteriaFetchWhenConditionsMet"
+```
+- Executes on iOS Simulator with accurate pass/fail reporting
+- Returns exit code 0 for success, 1 for failures
+- Shows detailed test counts and failure information
+- `--list` shows all test suites with test counts
+- Requires password for xcpretty installation (first run)
+
+## Project Structure
+```
+swift-sdk/
+├── swift-sdk/               # Main SDK source
+│   ├── Core/               # Public APIs and models
+│   ├── Internal/           # Internal implementation
+│   ├── SDK/               # Main SDK entry points
+│   └── ui-components/     # SwiftUI/UIKit components
+├── tests/                 # Test suites
+│   ├── unit-tests/        # Unit tests
+│   ├── ui-tests/         # UI automation tests
+│   └── endpoint-tests/   # API endpoint tests
+├── sample-apps/          # Example applications
+└── notification-extension/ # Push notification extension
+```
+
+## Key Classes
+- **IterableAPI**: Main SDK interface
+- **IterableConfig**: Configuration management
+- **InternalIterableAPI**: Core implementation
+- **UnknownUserManager**: Unknown user tracking
+- **LocalStorage**: Data persistence
+
+## Common Tasks
+
+### Adding New Features
+1. Build first: `./agent_build.sh`
+2. Implement in `swift-sdk/Internal/` or `swift-sdk/SDK/`
+3. Add tests in `tests/unit-tests/`
+4. Verify: `./agent_test.sh` (all tests) or `./agent_test.sh YourTestSuite` (specific suite)
+
+### Debugging Build Issues
+- Build script shows compilation errors with file paths
+- Check Xcode project references in `swift-sdk.xcodeproj/project.pbxproj`
+- Verify file renames are reflected in project file
+
+### Test Failures
+- Test script shows specific failures with line numbers and detailed error messages
+- Run failing tests individually: `./agent_test.sh "TestSuite.testMethod"`
+- Mock classes available in `tests/common/`
+- Update parameter names when refactoring APIs
+
+## Requirements
+- **macOS**: Required for Xcode builds
+- **Xcode**: Latest stable version
+- **Ruby**: For xcpretty (auto-installed)
+- **iOS Simulator**: For testing
+
+## Quick Start for AI Agents
+1. Run `./agent_build.sh` to verify project builds
+2. Run `./agent_test.sh` to check test health (or `./agent_test.sh TestSuite` for specific suite)
+3. Make changes to source files
+4. Re-run both scripts to validate
+5. Debug failing tests: `./agent_test.sh "TestSuite.testMethod"`
+6. Commit when both pass ✅
+
+## Test Filtering Examples
+```bash
+# Debug specific failing tests
+./agent_test.sh "IterableApiCriteriaFetchTests.testForegroundCriteriaFetchWhenConditionsMet"
+
+# Run a problematic test suite
+./agent_test.sh ValidateCustomEventUserUpdateAPITest
+
+# Check auth-related tests
+./agent_test.sh AuthTests
+```
+
+## AI Agent Memory System
+
+### 🧠 Update Instructions for AI Agents
+**IMPORTANT**: When you discover something useful while working on this codebase, update this README to help future AI agents. Add learnings to the sections below.
+
+### 📍 Code Location Map
+- **Auth Logic**: `swift-sdk/Internal/AuthManager.swift` (main auth manager), `swift-sdk/Internal/Auth.swift` (auth models)
+- **API Calls**: `swift-sdk/Internal/api-client/ApiClient.swift` (main client), `swift-sdk/Internal/Network/NetworkHelper.swift` (networking)
+- **Models**: `swift-sdk/Core/Models/` (all data structures - CommerceItem, IterableInAppMessage, etc.)
+- **Main Entry**: `swift-sdk/SDK/IterableAPI.swift` (public API), `swift-sdk/Internal/InternalIterableAPI.swift` (core implementation)
+- **Request Handling**: `swift-sdk/Internal/api-client/Request/` (online/offline processors)
+
+### 🛠️ Common Task Recipes
+
+**Add New API Endpoint:**
+1. Add path constant to `swift-sdk/Core/Constants.swift` in `Const.Path`
+2. Add method to `ApiClientProtocol.swift` and implement in `ApiClient.swift`
+3. Create request in `swift-sdk/Internal/api-client/Request/RequestCreator.swift`
+4. Add to `RequestHandlerProtocol.swift` and `RequestHandler.swift`
+
+**Modify Auth Logic:**
+- Main logic: `swift-sdk/Internal/AuthManager.swift`
+- Token storage: `swift-sdk/Internal/Utilities/Keychain/IterableKeychain.swift`
+- Auth failures: Handle in `RequestProcessorUtil.swift`
+
+**Add New Model:**
+- Create in `swift-sdk/Core/Models/YourModel.swift`
+- Make it `@objcMembers public class` for Objective-C compatibility
+- Implement `Codable` if it needs JSON serialization
+
+### 🐛 Common Failure Solutions
+
+**"Test X failed"** → Check test file in `tests/unit-tests/` - often parameter name mismatches after refactoring
+
+**"Build failed: file not found"** → Update `swift-sdk.xcodeproj/project.pbxproj` to include new/renamed files
+
+**"Auth token issues"** → Check `AuthManager.swift` and ensure JWT format is correct in tests
+
+**"Network request fails"** → Check endpoint in `Constants.swift` and request creation in `RequestCreator.swift`
+
+## Notes
+- Always test builds after refactoring
+- Parameter name changes require test file updates
+- Project file (`*.pbxproj`) may need manual updates for file renames
+- Sample apps demonstrate SDK usage patterns 

CHANGELOG.md

@@ -2,6 +2,27 @@
 
 All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/).
+
+## [6.6.0-beta3]
+
+- This release includes fixes for the Unknown user activation private beta:
+    - Criteria is now fetched on foregrounding the app by default. This feature can be turned off setting enableForegroundCriteriaFetch flag to false. 
+    - Unknown user ids are only generated once when multiple track calls are made.
+- Unknown user activation is currently in private beta. If you'd like to learn more about it or discuss using it, talk to your Iterable customer success manager (who can also provide detailed documentation).
+
+## [6.6.0-beta2]
+
+- This release fixes beta1 release which was released from the wrong branch.
+
+## [6.6.0-beta1]
+
+- This release includes initial support for Unknown user activation, a feature that allows marketers to convert valuable visitors into customers. With this feature, the SDK can:
+  - Fetch unknown user profile creation criteria from your Iterable project, and then automatically create Iterable user profiles for Unknown users who meet these criteria.
+  - Save information about a user's previous interactions with your application to their unknown user profile, after it's created.
+  - Display personalized messages for Unknown users (in-app, push, and embedded messages).
+  - Merge unknown user profiles into an existing, known user profiles (when needed).
+- Unknown user activation is currently in private beta. If you'd like to learn more about it or discuss using it, talk to your Iterable customer success manager (who can also provide detailed documentation).
+
 ## [Unreleased]
 
 ## [6.5.14]

CLAUDE.md

@@ -0,0 +1,7 @@
+# CLAUDE.md
+
+🤖 **AI Agent Instructions**
+
+Please read the `AGENT_README.md` file for comprehensive project information, development workflow, and testing procedures.
+
+All the information you need to work on this Iterable Swift SDK project is documented there. 

agent_build.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+
+# This script is to be used by LLMs and AI agents to build the Iterable Swift SDK on macOS.
+# It uses xcpretty to format the build output and only shows errors.
+# It also checks if the build is successful and exits with the correct status.
+
+# Check if running on macOS
+if [[ "$(uname)" != "Darwin" ]]; then
+    echo "❌ This script requires macOS to run Xcode builds"
+    exit 1
+fi
+
+# Make sure xcpretty is installed
+if ! command -v xcpretty &> /dev/null; then
+    echo "xcpretty not found, installing via gem..."
+    sudo gem install xcpretty
+fi
+
+echo "Building Iterable Swift SDK..."
+
+# Create a temporary file for the build output
+TEMP_OUTPUT=$(mktemp)
+
+# Run the build and capture all output
+xcodebuild \
+    -project swift-sdk.xcodeproj \
+    -scheme "swift-sdk" \
+    -configuration Debug \
+    -sdk iphonesimulator \
+    build > $TEMP_OUTPUT 2>&1
+
+# Check the exit status
+BUILD_STATUS=$?
+
+# Show errors and warnings if build failed
+if [ $BUILD_STATUS -eq 0 ]; then
+    echo "✅ Iterable SDK build succeeded!"
+else
+    echo "❌ Iterable SDK build failed with status $BUILD_STATUS"
+    echo ""
+    echo "🔍 Build errors:"
+    grep -E 'error:|fatal:' $TEMP_OUTPUT | head -10
+    echo ""
+    echo "⚠️  Build warnings:"
+    grep -E 'warning:' $TEMP_OUTPUT | head -5
+fi
+
+# Remove the temporary file
+rm $TEMP_OUTPUT
+
+exit $BUILD_STATUS