fix: Add Improved chain switching detection [P-1563] #127

yosriady · 2025-10-24T10:44:42Z

Note

Ensure CHAIN transitions are always tracked while other events on excluded chains are skipped; add previousChainId, refine shouldTrack, and include docs, example, and test stubs.

Core (src/FormoAnalytics.ts):
- Tracking logic: Refactor shouldTrack(eventType?, chainId?) to be context-aware; always track EventType.CHAIN, skip other events on tracking.excludeChains.
- Event routing: trackEvent() now passes type and payload.chainId to shouldTrack and improves skip logging; trackPageHit() calls shouldTrack(EventType.PAGE).
- Chain switching: onChainChanged() captures previousChainId, logs transitions, and emits chain({ chainId: nextChainId }, { previousChainId }) without redundant currentChainId assignment.
Docs: Add CHAIN_SWITCHING_IMPROVEMENTS.md, CHAIN_SWITCHING_FIX_SUMMARY.md, IMPLEMENTATION_COMPLETE.md, and QUICK_REFERENCE.md describing behavior and guidance.
Examples: Add examples/chain-switching-example.ts demonstrating excludeChains and transition tracking.
Tests: Add scaffold test/lib/chain-switching.spec.ts (skipped/TODO) for chain switching and exclusions.

^{Written by Cursor Bugbot for commit 1187153. This will update automatically on new commits. Configure here.}

linear · 2025-10-24T10:44:45Z

P-1563 SDK: Improve reliability of excludeChains / this.currentChainId when switching chains

greptile-apps

Greptile Overview

Greptile Summary

This PR fixes chain switching detection when using excludeChains configuration. The implementation adds context-aware tracking that distinguishes between chain transition events (always tracked) and other events like transactions/signatures (excluded on specified chains).

Key changes:

Enhanced shouldTrack() method with eventType and chainId parameters for context-aware decisions
Chain transition events (EventType.CHAIN) are now always tracked, even for excluded chains, to capture valuable analytics about network switching behavior
onChainChanged() now captures previousChainId before updating state and includes it in event properties
trackEvent() extracts chainId from event payload to ensure correct chain is checked

Behavior improvement:

Before: Switching TO an excluded chain wouldn't track the transition
After: All chain transitions are tracked with previousChainId included, while other events (transactions, signatures) correctly respect excludeChains exclusion

Documentation:

Added 4 comprehensive markdown files documenting the fix, improvements, and usage examples
Created example file with 5 usage scenarios demonstrating proper configuration

Testing:

Test file created with comprehensive test cases but marked as describe.skip - tests are not implemented yet

Confidence Score: 3/5

This PR is mostly safe to merge but has minor implementation concerns and lacks test coverage
The core logic is sound and addresses the reported issue effectively. However, confidence is reduced due to: (1) redundant currentChainId assignment in two places, and (2) comprehensive test suite defined but completely skipped/unimplemented, leaving the changes untested
test/lib/chain-switching.spec.ts requires test implementation before merging to production

Important Files Changed

File Analysis

Filename	Score	Overview
src/FormoAnalytics.ts	4/5	Enhanced chain switching detection with context-aware tracking; properly handles `excludeChains` for transitions vs other events
test/lib/chain-switching.spec.ts	2/5	Test file created with comprehensive test cases but all tests are skipped (not implemented)

Sequence Diagram

sequenceDiagram
    participant User
    participant Wallet
    participant SDK as FormoAnalytics SDK
    participant shouldTrack
    participant Analytics as Analytics Backend

    Note over User,Analytics: Chain Switching Flow

    User->>Wallet: Switch from Chain 1 to Chain 41455 (excluded)
    Wallet->>SDK: chainChanged event (0xa1ef)
    SDK->>SDK: onChainChanged(provider, "0xa1ef")
    Note over SDK: Capture previousChainId = 1
    SDK->>SDK: Parse chainId: 41455
    SDK->>SDK: Update currentChainId = 41455
    SDK->>SDK: chain({ chainId: 41455, address }, { previousChainId: 1 })
    SDK->>SDK: trackEvent(CHAIN, { chainId: 41455 })
    SDK->>shouldTrack: shouldTrack(CHAIN, 41455)
    Note over shouldTrack: Check if 41455 in excludeChains<br/>EventType is CHAIN, so return TRUE
    shouldTrack-->>SDK: true (always track chain transitions)
    SDK->>Analytics: Track chain event { chainId: 41455, previousChainId: 1 }

    Note over User,Analytics: Transaction on Excluded Chain

    User->>SDK: transaction({ chainId: 41455, ... })
    SDK->>SDK: trackEvent(TRANSACTION, { chainId: 41455 })
    SDK->>shouldTrack: shouldTrack(TRANSACTION, 41455)
    Note over shouldTrack: Check if 41455 in excludeChains<br/>EventType is TRANSACTION, so return FALSE
    shouldTrack-->>SDK: false (exclude transaction)
    SDK->>SDK: Skip tracking (log: "Skipping transaction on excluded chain")

    Note over User,Analytics: Switch Back to Normal Chain

    User->>Wallet: Switch from Chain 41455 to Chain 1
    Wallet->>SDK: chainChanged event (0x1)
    SDK->>SDK: onChainChanged(provider, "0x1")
    Note over SDK: Capture previousChainId = 41455
    SDK->>SDK: Parse chainId: 1
    SDK->>SDK: Update currentChainId = 1
    SDK->>SDK: chain({ chainId: 1, address }, { previousChainId: 41455 })
    SDK->>SDK: trackEvent(CHAIN, { chainId: 1 })
    SDK->>shouldTrack: shouldTrack(CHAIN, 1)
    Note over shouldTrack: Chain 1 not in excludeChains<br/>Return TRUE
    shouldTrack-->>SDK: true
    SDK->>Analytics: Track chain event { chainId: 1, previousChainId: 41455 }

    Note over User,Analytics: Transaction on Normal Chain

    User->>SDK: transaction({ chainId: 1, ... })
    SDK->>SDK: trackEvent(TRANSACTION, { chainId: 1 })
    SDK->>shouldTrack: shouldTrack(TRANSACTION, 1)
    Note over shouldTrack: Chain 1 not in excludeChains<br/>Return TRUE
    shouldTrack-->>SDK: true
    SDK->>Analytics: Track transaction event

Additional Comments (1)

src/FormoAnalytics.ts, line 390 (link)

style: currentChainId updated twice for chain events: once here in chain() method (line 390) and once in onChainChanged() (line 1041). When onChainChanged calls chain(), the chain ID gets set twice - first at line 1041 before calling chain(), then again here at line 390 when chain() executes. This redundancy could cause confusion.

_{7 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

yosriady · 2025-10-24T11:12:18Z

@greptile

yosriady · 2025-10-24T11:12:25Z

bugbot run

cursor

✅ Bugbot reviewed your changes and found no bugs!

greptile-apps

Greptile Overview

Greptile Summary

Enhances chain switching detection to always track CHAIN transition events while respecting excludeChains for other event types, and adds previousChainId to chain event properties for better analytics context.

Key improvements:

Captures previousChainId before chain transitions for analytics
Context-aware shouldTrack() method accepts eventType and chainId parameters
CHAIN events always tracked (even on excluded chains) to capture network switching behavior
Other events (transactions, signatures) properly filtered on excluded chains
Better logging for chain transitions and tracking decisions
Fixed chain ID 0 handling with !== undefined check

Minor concerns:

Type coercion on line 1460 could potentially mask bugs if unexpected types are passed
Tests marked as skipped - implementation should be validated with actual test coverage

Confidence Score: 4/5

This PR is safe to merge with low risk - logic improvements are well-reasoned and backward compatible
Score reflects solid implementation of chain switching improvements with clear documentation. The logic for always tracking CHAIN events while filtering other events on excluded chains is sound. Minor deduction for type coercion that could be more defensive, and skipped tests that should be implemented before production use. No breaking changes or critical issues identified.
Pay attention to src/FormoAnalytics.ts line 1460 for potential type safety improvements

Important Files Changed

File Analysis

Filename	Score	Overview
src/FormoAnalytics.ts	4/5	Improved chain switching detection with previousChainId tracking, context-aware shouldTrack logic, and better handling of excludeChains - minor edge case concerns around type coercion

Sequence Diagram

sequenceDiagram
    participant Provider as EIP1193 Provider
    participant Analytics as FormoAnalytics
    participant ShouldTrack as shouldTrack()
    participant Backend as Analytics Backend
    
    Note over Provider,Backend: Chain Switching Flow with excludeChains
    
    Provider->>Analytics: chainChanged(newChainIdHex)
    activate Analytics
    Analytics->>Analytics: previousChainId = currentChainId
    Analytics->>Analytics: nextChainId = parseChainId(hex)
    Analytics->>Analytics: Log transition (from → to)
    
    Analytics->>Analytics: chain({chainId: nextChainId, ...}, {previousChainId})
    activate Analytics
    Note over Analytics: Line 390: currentChainId updated here
    Analytics->>Analytics: currentChainId = nextChainId
    
    Analytics->>Analytics: trackEvent(CHAIN, payload, properties)
    activate Analytics
    Analytics->>Analytics: chainIdForCheck = payload.chainId
    
    Analytics->>ShouldTrack: shouldTrack(EventType.CHAIN, chainIdForCheck)
    activate ShouldTrack
    
    alt Chain ID in excludeChains
        ShouldTrack->>ShouldTrack: eventType === EventType.CHAIN?
        Note over ShouldTrack: CHAIN events always tracked<br/>to capture network transitions
        ShouldTrack-->>Analytics: return true
    else Chain ID not excluded
        ShouldTrack-->>Analytics: return true
    end
    deactivate ShouldTrack
    
    Analytics->>Backend: Send CHAIN event with previousChainId
    Backend-->>Analytics: Event tracked
    deactivate Analytics
    deactivate Analytics
    deactivate Analytics
    
    Note over Provider,Backend: Subsequent Event on Excluded Chain
    
    Provider->>Analytics: Transaction event on excluded chain
    activate Analytics
    Analytics->>Analytics: trackEvent(TRANSACTION, payload)
    activate Analytics
    Analytics->>ShouldTrack: shouldTrack(TRANSACTION, excludedChainId)
    activate ShouldTrack
    
    ShouldTrack->>ShouldTrack: Chain in excludeChains?
    ShouldTrack->>ShouldTrack: eventType === CHAIN? No
    Note over ShouldTrack: Non-CHAIN events filtered<br/>on excluded chains
    ShouldTrack-->>Analytics: return false
    deactivate ShouldTrack
    
    Analytics->>Analytics: Skip event
    Note over Analytics: Event not sent to backend
    deactivate Analytics
    deactivate Analytics

_{2 files reviewed, 1 comment}

_{Edit Code Review Agent Settings | Greptile}

src/FormoAnalytics.ts

yosriady · 2025-10-26T13:01:38Z

This is redundant

[P-1563] Improve chain switching detection

b1e28ff

This comment was marked as outdated.

Sign in to view

greptile-apps bot reviewed Oct 24, 2025

View reviewed changes

fix

1187153

cursor bot reviewed Oct 24, 2025

View reviewed changes

greptile-apps bot reviewed Oct 24, 2025

View reviewed changes

src/FormoAnalytics.ts Show resolved Hide resolved

yosriady changed the title ~~[P-1563] Fix: Add Improved chain switching detection~~ fix: Add Improved chain switching detection [P-1563] Oct 26, 2025

yosriady closed this Oct 26, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix: Add Improved chain switching detection [P-1563] #127

fix: Add Improved chain switching detection [P-1563] #127

Uh oh!

yosriady commented Oct 24, 2025 •

edited by cursor bot

Loading

Uh oh!

linear bot commented Oct 24, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

greptile-apps bot left a comment •

edited

Loading

Uh oh!

yosriady commented Oct 24, 2025

Uh oh!

yosriady commented Oct 24, 2025

Uh oh!

cursor bot left a comment

Uh oh!

greptile-apps bot left a comment

Uh oh!

Uh oh!

yosriady commented Oct 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

fix: Add Improved chain switching detection [P-1563] #127

fix: Add Improved chain switching detection [P-1563] #127

Uh oh!

Conversation

yosriady commented Oct 24, 2025 • edited by cursor bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

linear bot commented Oct 24, 2025

Uh oh!

This comment was marked as outdated.

Uh oh!

greptile-apps bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Greptile Overview

Greptile Summary

Confidence Score: 3/5

Important Files Changed

Sequence Diagram

Additional Comments (1)

Uh oh!

yosriady commented Oct 24, 2025

Uh oh!

yosriady commented Oct 24, 2025

Uh oh!

cursor bot left a comment

Choose a reason for hiding this comment

✅ Bugbot reviewed your changes and found no bugs!

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Greptile Overview

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Sequence Diagram

Uh oh!

Uh oh!

yosriady commented Oct 26, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

yosriady commented Oct 24, 2025 •

edited by cursor bot

Loading

greptile-apps bot left a comment •

edited

Loading