Migration Guides

Migration guides for upgrading between major SDK versions.

Web SDK Migrations

Latest Migrations

• Migrating to v1.2 - Latest version
• Migrating to v1.1
• Migrating to v1.0 - From beta

Quick Version Check

import SDK from "@your-org/web-sdk";

console.log("SDK Version:", SDK.VERSION);
// Example output: "1.2.0"

Mobile SDK Migrations

iOS

• v6.x → v7.x Migration - SwiftUI support, async/await
• v5.x → v6.x Migration - Swift 5.0, iOS 11+

Android

• v6.x → v7.x Migration - Kotlin coroutines, Android 5+
• v5.x → v6.x Migration - AndroidX, Kotlin

React Native

• v6.x → v7.x Migration
• v5.x → v6.x Migration

General Migration Process

Step 1: Review Breaking Changes

Before upgrading, review the changelog for your target version:

• Web SDK Changelog
• iOS SDK Changelog
• Android SDK Changelog

Step 2: Update Dependencies

NPM

npm install @your-org/web-sdk@latest

Yarn

yarn upgrade @your-org/web-sdk

CocoaPods

# Update Podfile
pod 'YourOrgSDK', '~> 7.0'

# Install
pod install

Android

// Update build.gradle
implementation 'com.yourorg:android-sdk:7.0.1'

Step 3: Update Code

Follow the specific migration guide for your version upgrade.

Step 4: Test Thoroughly

// Enable debug mode during migration
const sdk = new SDK({
  apiKey: "test-api-key",
  environment: "test",
  debugMode: true,
  verboseLogging: true,
});

// Test core functionality
sdk.initialize().then(() => {
  console.log("✓ Initialization successful");

  // Test event tracking
  sdk.trackEvent("test_event", { test: true });

  // Test user identification
  sdk.setUser({ userId: "test-user" });
});

Step 5: Deploy Gradually

1. Deploy to test environment first
2. Monitor for errors
3. Deploy to staging
4. Monitor analytics dashboard
5. Deploy to production gradually (e.g., 10% → 50% → 100%)

Breaking Changes Overview

Web SDK v1.2

✅ No breaking changes - Fully backward compatible

Web SDK v1.1

✅ No breaking changes - Fully backward compatible

Web SDK v1.0

From beta (v0.x):

Constructor API Changed

// ❌ Old (v0.x)
SDK.init({
  apiKey: "key",
});

// ✅ New (v1.0+)
const sdk = new SDK({
  apiKey: "key",
});
sdk.initialize();

Event Method Renamed

// ❌ Old (v0.x)
sdk.track("event_name", data);

// ✅ New (v1.0+)
sdk.trackEvent("event_name", data);

Configuration Changes

// ❌ Old (v0.x)
SDK.init({
  apiKey: "key",
  autoPageTracking: true,
});

// ✅ New (v1.0+)
const sdk = new SDK({
  apiKey: "key",
  autoTrack: true, // Renamed
});

iOS SDK v7.0

Minimum iOS Version

// ❌ Old (v6.x) - iOS 11.0+
// ✅ New (v7.x) - iOS 12.0+ required

API Modernization

// ❌ Old (v6.x)
YourOrgSDK.shared.trackScreen("Home")

// ✅ New (v7.x)
YourOrgSDK.trackScreenView("Home")

Async/Await Support

// ❌ Old (v6.x) - Callbacks
YourOrgSDK.initialize { result in
    switch result {
    case .success: print("Success")
    case .failure(let error): print(error)
    }
}

// ✅ New (v7.x) - Async/await
Task {
    do {
        try await YourOrgSDK.initialize()
        print("Success")
    } catch {
        print(error)
    }
}

// Both callback and async/await supported in v7.x

Compatibility Table

Web SDK

Your Version	Can Upgrade To	Breaking Changes	Effort
v0.x	v1.0	⚠️ Yes	Medium
v1.0	v1.1	✅ No	Low
v1.0	v1.2	✅ No	Low
v1.1	v1.2	✅ No	Low

iOS SDK

Your Version	Can Upgrade To	Breaking Changes	Effort
v5.x	v6.0	⚠️ Yes	Medium
v5.x	v7.0	⚠️ Yes	High
v6.x	v7.0	⚠️ Yes	Medium

Android SDK

Your Version	Can Upgrade To	Breaking Changes	Effort
v5.x	v6.0	⚠️ Yes	Medium
v5.x	v7.0	⚠️ Yes	High
v6.x	v7.0	⚠️ Yes	Medium

Automated Migration Tools

Codemod for Web SDK v0.x → v1.0

npx @your-org/codemod v0-to-v1 ./src

This will automatically update:

• Constructor calls
• Method names
• Configuration options

Manual Review Required

Some changes require manual updates:

• Custom event implementations
• Framework-specific integrations
• Advanced configuration

Deprecation Warnings

Stay ahead of changes by monitoring deprecation warnings:

// Enable deprecation warnings
const sdk = new SDK({
  apiKey: "key",
  showDeprecationWarnings: true,
});

// Console will show:
// ⚠️ Warning: sdk.track() is deprecated. Use sdk.trackEvent() instead.
// This method will be removed in v2.0.0

Version Support Policy

• Major versions: Supported for 12 months after next major release
• Minor versions: Supported until next major release
• Patch versions: Always use latest patch

Current Support Status

Version	Status	End of Support
Web v1.2.x	✅ Active	Current
Web v1.1.x	⚠️ Maintenance	2025-06-01
Web v1.0.x	⚠️ Maintenance	2025-03-01
Web v0.x	❌ Unsupported	Ended
iOS v7.x	✅ Active	Current
iOS v6.x	⚠️ Maintenance	2025-05-01
iOS v5.x	❌ Unsupported	Ended

Need Help?

• Review specific migration guides
• Check changelog for detailed changes
• Join community forum for migration questions
• Contact support for migration assistance

Best Practices

Before Migration

1. ✅ Read full migration guide
2. ✅ Review changelog
3. ✅ Update dependencies in test environment first
4. ✅ Create git branch for migration
5. ✅ Run existing tests

During Migration

1. ✅ Enable debug mode
2. ✅ Update code incrementally
3. ✅ Test each change
4. ✅ Monitor console for warnings
5. ✅ Update tests

After Migration

1. ✅ Verify all features work
2. ✅ Check analytics dashboard
3. ✅ Monitor error rates
4. ✅ Update documentation
5. ✅ Deploy gradually