Custom Callbacks

Run your own C# code when a paywall button asks for it, then send success or failure back so the paywall can branch on the result.

A custom callback lets a paywall ask your game to do some work and wait for the answer. You add a Custom Callback action to a paywall button. When the player taps it, Superwall calls your C# handler. Your handler returns success or failure, and the paywall runs the matching actions.

Use it for work that lives in your game or on your server. For example, create an account through your own API, check a code the player typed, or look up a value and show it on the paywall.

Requirements

Unity SDK 0.4.1 or later.
iOS builds need Unity SDK 0.6.0 or later. Versions 0.4.1 and 0.5.0 fail pod install because they can't find the SuperwallKit version they need.
On Android, paywalls must use the default in-window presentation, AndroidPaywallPresentation.InWindow. See Limitations.
The placement must be registered with a PaywallPresentationHandler that sets OnCustomCallback.

Add the action to your paywall

Open your paywall in the paywall editor.
Select the button or other element that should run the callback.
Under Tap Behavior, click + Add Action.
Choose Custom Callback.
Enter a Name, such as createAccount. Your C# handler uses this name to tell callbacks apart.
Choose a Behavior: Blocking or Non-blocking. See Blocking and non-blocking callbacks.
To send values to your game, click + Add Variable and pick the paywall variables to send.
Add follow-up actions under On Success and On Failure.
Publish the paywall.

For every option on the action, see Tap Behaviors.

Handle the callback in your game

Set OnCustomCallback on the PaywallPresentationHandler you pass to RegisterPlacement. Write it as an async lambda so it can wait on a network request without blocking the main thread.

using System.Collections.Generic;
using Superwall;

var handler = new PaywallPresentationHandler
{
    OnCustomCallback = async (callback) =>
    {
        if (callback.Name != "createAccount")
        {
            return CustomCallbackResult.Failure();
        }

        // Keys are the variable paths you picked in the editor, such as "user.email".
        object email = null;
        callback.Variables?.TryGetValue("user.email", out email);
        var signup = await MyAccountApi.CreateAccountAsync(email as string);

        if (signup.Succeeded)
        {
            return CustomCallbackResult.Success(new Dictionary<string, object>
            {
                { "username", signup.Username }
            });
        }

        return CustomCallbackResult.Failure(new Dictionary<string, object>
        {
            { "message", signup.Error }
        });
    }
};

Superwall.Shared.RegisterPlacement("signup", handler: handler);

Replace MyAccountApi with your own code. The handler gets a CustomCallback and returns a CustomCallbackResult.

`CustomCallback`

Prop

Type

`CustomCallbackResult`

Return one of these from your handler:

// The paywall runs its On Success actions.
CustomCallbackResult.Success(new Dictionary<string, object> { { "key", "value" } });

// The paywall runs its On Failure actions.
CustomCallbackResult.Failure(new Dictionary<string, object> { { "error", "Something went wrong" } });

Both take an optional data dictionary. Values can be strings, numbers, booleans, lists and dictionaries.

Read the result in the paywall

The paywall can read the data you return as callbacks.NAME.data.KEY. In the example above, a successful callback makes the username available as callbacks.createAccount.data.username. A failed one makes the error available as callbacks.createAccount.data.message.

Blocking and non-blocking callbacks

The Behavior you choose in the paywall editor decides whether the paywall waits for your handler.

Blocking: the paywall waits for your handler to finish before it runs the next action. Use this when the next step depends on the result, such as checking a form before moving on.
Non-blocking: the paywall runs the next action right away. Its On Success or On Failure actions still run when your handler finishes.

A blocking callback holds the paywall until your task completes. Superwall doesn't add a timeout, so give network requests in your handler their own timeout.

When the paywall gets a failure

The paywall runs its On Failure actions, with no data, when:

Your handler throws an exception.
Your handler's task is cancelled.
Your handler returns null.
The placement's PaywallPresentationHandler has no OnCustomCallback.

Superwall logs a warning or error in the Unity console for each of these. If you register the placement with no PaywallPresentationHandler at all, the paywall gets a failure and nothing is logged in Unity.

Limitations

On Android, custom callbacks only work with the default in-window presentation. With AndroidPaywallPresentation.Activity, Unity is paused while the paywall is open, so every callback fails straight away and logs an error to Logcat. See the AndroidPresentation option in Advanced Configuration.
A custom callback is different from a custom action. HandleCustomPaywallAction on your Superwall delegate only tells your game that a button was tapped. It can't send anything back to the paywall.

On this page