Exception Callbacks

• Types of Exception

• Callback Register & Reception

Exception Callbacks refers to a mechanism that notifies your application when an exception (error) occurs inside the SDK. When the SDK encounters unexpected events such as low memory warnings, webview injection failures, or cases where the application context is unavailable, it automatically sends exception details to the server and exposes exception callbacks that you can register within your application. These callbacks are available across the core SDK and all supported cross-platform libraries, enabling you to implement the same exception-handling logic regardless of whether your application is native or cross-platform.

The SDK exposes exception callbacks that you can register within your application. Using these callbacks, you can:

• Receive real-time notifications when SDK exceptions occur

• Inspect exception details such as type and context

• Implement custom handling logic (for example, logging, analytics, or fallback behavior)

Info:

In a self-hosted SDK setup, the SDK sends exceptions to the backend automatically. It captures these exceptions internally and provides a mechanism for you to handle them according to your application’s needs.

Types of Exception

The SDK captures the following types of exceptions:

• Low memory exceptions: Occurs when the device runs out of available memory.

• Leap crash exceptions: Occurs when the SDK crashes unexpectedly.

  a. All try-catch exceptions (Android): Includes Graceful exit exceptions within try-catch blocks.

  b. JSON encoding and decoding exceptions (iOS): Occurs when JSON data fails to encode or decode properly.

• AUI exceptions: Occur when an error affects Adaptive User Interface (AUI) elements.

  a. Application context not available (Android): Occurs when the Android application context is missing or inaccessible.

  b. Leap AUI element errors: Occur when specific AUI elements fail to load or behave correctly.

• JS exceptions: Occur when JavaScript code in the app faces an error.

  a. Customer webview injection failure: Occur when the SDK fails to inject custom scripts into a webview.

  b. JS not loading or incorrect JS: Occurs when JavaScript fails to load or is invalid.

• Public method exceptions (Android)

Callback register and reception

To capture SDK exceptions, add the following code to your App component:

Leap.shared.registerExceptionCallback(self, callbackLevels:[.MEMORY,.CRASH,.AUI,.JS,.PUBLIC_METHOD])

extension AppDelegate:LeapCallback {
  func exceptionCallbackEvent(eventInfo: [String:AnyHashable], exceptionType:LeapExceptionType) {
        print("Exception Event = \(eventInfo)")
  }
}

public static void registerExceptionCallback(String[] callbackLevels, LeapExceptionCallbacks exceptionCallbacks)

public interface LeapExceptionCallbacks {
    void onException(Map<String, Object> exceptionData);
}

const onLeapExceptionCallback = event => {
    console.log('Leap Exception Event: ', event);
};

DeviceEventEmitter.addListener('LeapExceptionCallbacks', onLeapExceptionCallback);

cordova.plugins.LeapiOS.setLeapExceptionEventCallback((leapExceptionEvent) =>{
    console.log(JSON.stringify(leapExceptionEvent,null,2));
})

cordova.plugins.LeapAndroid.setLeapExceptionEventCallback((leapExceptionEvent)=> {
  console.log(JSON.stringify(leapExceptionEvent, null, 2))
})

LeapPlugin.addListener("leapExceptionCallbacks", (event: LeapExceptionCallbacks) => {
    console.log("Leap Events: ", event);
})

// Example for Flutter
import 'package:your_sdk/your_sdk.dart';

void main() {
    YourSDK.registerCallback((exception) {
        print('Exception caught: $exception');
    });

// Platforms/Android/MainApplication.cs
using System;
using Android.App;
using Android.OS;
using Android.Runtime;
using Microsoft.Maui;
using Microsoft.Maui.Hosting;

// Leap bindings (adjust namespaces if yours differ)
using IS.Leap.Android;          // For Leap, LeapExceptionCallbackLevel, ILeapExceptionCallbacks, LeapExceptionData
using IS.Leap.Android.Aui;      // If AUI types are needed elsewhere
using IS.Leap.Android.Creator;

namespace Calculator;

[Application]
public class MainApplication : MauiApplication
{
    public MainApplication(IntPtr handle, JniHandleOwnership ownership)
        : base(handle, ownership) { }

    protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();

    public override void OnCreate()
    {
        base.OnCreate();

        // Start Leap
        Leap.Start("f4b7b514-5b84-431c-9de5-c26b2ef4f720");

        // Register exception callbacks (run once per process)
        RegisterLeapExceptionCallbacksOnce();

        // Start LeapCreator
        LeapCreator.Start("f4b7b514-5b84-431c-9de5-c26b2ef4f720");
    }

    private static bool _callbacksRegistered;

    private static void RegisterLeapExceptionCallbacksOnce()
    {
        if (_callbacksRegistered) return;

        var levels = new[]
        {
            LeapExceptionCallbackLevel.Memory,
            LeapExceptionCallbackLevel.Js,
            LeapExceptionCallbackLevel.Crash,
            LeapExceptionCallbackLevel.Aui,
            LeapExceptionCallbackLevel.PublicMethod
        };

        // If your binding exposes a delegate overload, you can also pass: data => { ... }
        Leap.RegisterExceptionCallback(levels, new MyLeapExceptionCallbacks());

        _callbacksRegistered = true;
    }
}

/// <summary>
/// Implementation of the Leap exception callback receiver.
/// Adjust method name/signature to match your generated binding if it differs.
/// </summary>
[Preserve(AllMembers = true)]
public sealed class MyLeapExceptionCallbacks : Java.Lang.Object, ILeapExceptionCallbacks
{
    // Typical Xamarin.Android binding for a SAM interface surfaces a single method.
    // If your generated interface uses a different method name or params, let your IDE
    // implement the interface to see the exact signature and update this method accordingly.

    public void OnException(IDictionary<string, Java.Lang.Object> exceptionData)
    {
        System.Diagnostics.Debug.WriteLine($"LEAP EXCEPTION CALLBACK: {exceptionData}");
        Android.Util.Log.Info("Leap", $"LEAP EXCEPTION CALLBACK: {exceptionData}");
    }
}

public class AppDelegate : UIResponder, IUIApplicationDelegate, ILeapExceptionCallBack
    {
        [Export("window")]
        public UIWindow Window { get; set; }
        [Export("application:didFinishLaunchingWithOptions:")]
        public bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
        {
            Leap.Shared.Start("<API_KEY>");
            LeapExceptionCallBackTypes[] callbackTypes = { LeapExceptionCallBackTypes.Memory, LeapExceptionCallBackTypes.Crash, LeapExceptionCallBackTypes.Memory};
            var nsArray = NSArray.FromNSObjects(
                callbackTypes.Select(t => new NSNumber((long)t)).ToArray()
            );
            NSObject nsObject = nsArray;
            Leap.Shared.RegisterExceptionCallback(this,nsObject);
            return true;
        }
        void ExceptionCallbackEventWithEventInfo(NSObject eventInfo, LeapExceptionCallBackTypes exceptionType) {
           Print(eventInfo);
        }
    }