Add custom callbacks message and interface

[ianrumac]

Changes in this pull request

• Enable custom callbacks from paywall to the app
• Adds a new method to PaywallPresentationHandler called onCustomCallback that allows user to handle custom callback requests

Checklist

• All unit tests pass.
• All UI tests pass.
• Demo project builds and runs.
• I added/updated tests or detailed why my change isn't tested.
• I added an entry to the CHANGELOG.md for any breaking changes, enhancements, or bug fixes.
• I have run ktlint in the main directory and fixed any issues.
• I have updated the SDK documentation as well as the online docs.
• I have reviewed the contributing guide

Greptile Summary

Adds custom callback support enabling bidirectional communication between paywalls and app code.

• Added new CustomCallback, CustomCallbackBehavior, and CustomCallbackResult data classes to represent callback requests and responses
• Implemented CustomCallbackRegistry using ConcurrentHashMap for thread-safe handler storage with proper lifecycle management (registration on present, cleanup on dismiss)
• Added onCustomCallback method to PaywallPresentationHandler as the public API for apps to handle custom callback requests
• Integrated callback message parsing (request_callback) and response sending (callback_result) in PaywallMessageHandler
• Properly wired callbacks through the dependency injection system and paywall lifecycle
• Comprehensive test coverage including unit tests for registry operations and integration tests for message handling edge cases
• Exception handling ensures failures return appropriate error responses to the webview

Confidence Score: 5/5

• Safe to merge with no identified issues
• Implementation follows SDK patterns with proper thread safety, error handling, lifecycle management, and comprehensive test coverage. No logic errors or security concerns identified.
• No files require special attention

Important Files Changed

Filename	Overview
superwall/src/main/java/com/superwall/sdk/paywall/presentation/CustomCallback.kt	Added data classes and enums for custom callback system with clear documentation
superwall/src/main/java/com/superwall/sdk/paywall/presentation/CustomCallbackRegistry.kt	Added thread-safe registry using ConcurrentHashMap with proper lifecycle management
superwall/src/main/java/com/superwall/sdk/paywall/presentation/PaywallPresentationHandler.kt	Added public API method with comprehensive documentation and usage examples
superwall/src/main/java/com/superwall/sdk/paywall/presentation/PublicPresentation.kt	Integrated callback registration/unregistration into paywall lifecycle correctly
superwall/src/main/java/com/superwall/sdk/paywall/view/webview/messaging/PaywallMessageHandler.kt	Implemented callback handling with proper error handling and async execution

Sequence Diagram

sequenceDiagram
    participant App as App Code
    participant Handler as PaywallPresentationHandler
    participant Registry as CustomCallbackRegistry
    participant Superwall as Superwall
    participant WebView as PaywallView/WebView
    participant MsgHandler as PaywallMessageHandler
    
    Note over App,Handler: Registration Phase
    App->>Handler: register(event, handler)
    App->>Handler: handler.onCustomCallback { callback -> ... }
    Handler->>Handler: Store onCustomCallbackHandler
    
    Note over Superwall,Registry: Presentation Phase
    Superwall->>Registry: register(paywallId, handler)
    Superwall->>WebView: Present Paywall
    
    Note over WebView,MsgHandler: Callback Request
    WebView->>MsgHandler: postMessage("request_callback")
    MsgHandler->>MsgHandler: Parse PaywallMessage.RequestCallback
    MsgHandler->>Superwall: eventDidOccur(RequestCallback)
    
    Note over MsgHandler,Registry: Handler Execution
    MsgHandler->>Registry: getHandler(paywallId)
    Registry-->>MsgHandler: Return handler or null
    
    alt Handler exists
        MsgHandler->>App: Invoke handler(CustomCallback)
        App-->>MsgHandler: Return CustomCallbackResult
        MsgHandler->>WebView: sendCallbackResult(success/failure)
    else No handler
        MsgHandler->>WebView: sendCallbackResult(failure)
    end
    
    Note over Superwall,Registry: Dismissal Phase
    WebView->>Superwall: Paywall Dismissed
    Superwall->>Registry: unregister(paywallId)
    Registry->>Registry: Remove handler

Loading

[greptile-apps]

Greptile's behavior is changing!

From now on, if a review finishes with no comments, we will not post an additional "statistics" comment to confirm that our review found nothing to comment on. However, you can confirm that we reviewed your changes in the status check section.

_{This feature can be toggled off in your Code Review Settings by deselecting "Create a status check for each PR".}