Manejar eventos de onboarding en Unity SDK

Antes de empezar, asegúrate de que:

1. Has instalado el SDK de Adapty para Unity 3.14.0 o posterior.
2. Has creado un onboarding.
3. Has añadido el onboarding a un placement.

Los onboardings configurados con el builder generan eventos a los que tu app puede responder. A continuación se explica cómo hacerlo.

Para controlar o monitorizar los procesos que ocurren en la pantalla de onboarding dentro de tu app de Unity, implementa la interfaz AdaptyOnboardingsEventsListener.

Acciones personalizadas

En el builder, puedes añadir una acción personalizada a un botón y asignarle un ID.

Luego, puedes usar este ID en tu código y gestionarlo como una acción personalizada. Por ejemplo, si un usuario pulsa un botón personalizado, como Login o Allow notifications, el método OnboardingViewOnCustomAction se activará con el parámetro actionId siendo el Action ID del builder. Puedes crear tus propios IDs, como “allowNotifications”.

Para gestionar los eventos del onboarding, implementa la interfaz AdaptyOnboardingsEventsListener:

public class OnboardingManager : MonoBehaviour, AdaptyOnboardingsEventsListener
{
    void Start()
    {
        Adapty.SetOnboardingsEventsListener(this);
    }

    public void OnboardingViewOnCustomAction(
        AdaptyUIOnboardingView view,
        AdaptyUIOnboardingMeta meta,
        string actionId
    )
    {
        if (actionId == "allowNotifications") {
            // request notification permissions
        }
    }
    
    public void OnboardingViewDidFailWithError(
        AdaptyUIOnboardingView view,
        AdaptyError error
    )
    {
        // handle errors
    }

    // Implement other required interface methods (see examples below)
}

{
  "actionId": "allowNotifications",
  "meta": {
    "onboardingId": "onboarding_123",
    "screenClientId": "profile_screen",
    "screenIndex": 0,
    "screensTotal": 3
  }
}

Cerrar el onboarding

El onboarding se considera cerrado cuando el usuario pulsa un botón con la acción Close asignada.

Implementa el método OnboardingViewOnCloseAction en tu clase:

public class OnboardingManager : MonoBehaviour, AdaptyOnboardingsEventsListener
{
    public void OnboardingViewOnCloseAction(
        AdaptyUIOnboardingView view,
        AdaptyUIOnboardingMeta meta,
        string actionId
    )
    {
        view.Dismiss((error) => {
            if (error != null) {
                // handle the error
            }
        });
    }
    
    // ... other interface methods
}

{
  "action_id": "close_button",
  "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "final_screen",
    "screen_index": 3,
    "total_screens": 4
  }
}

Abrir un paywall

La forma más fluida de trabajar con paywalls en onboardings es hacer que el ID de acción sea igual al ID del placement del paywall. Así, tras el evento OnboardingViewOnPaywallAction, puedes usar el ID del placement para obtener y abrir el paywall de inmediato. Ten en cuenta que, en iOS, solo se puede mostrar una vista (paywall u onboarding) en pantalla al mismo tiempo. Si presentas un paywall encima de un onboarding, no podrás controlar el onboarding en segundo plano mediante código. Si intentas cerrar el onboarding, se cerrará el paywall en su lugar, dejando el onboarding visible. Para evitar esto, cierra siempre la vista del onboarding antes de presentar el paywall.

public class OnboardingManager : MonoBehaviour, AdaptyOnboardingsEventsListener
{
    public void OnboardingViewOnPaywallAction(
        AdaptyUIOnboardingView view,
        AdaptyUIOnboardingMeta meta,
        string actionId
    )
    {
        // Dismiss onboarding before presenting paywall
        view.Dismiss((dismissError) => {
            if (dismissError != null) {
                // handle the error
                return;
            }

            Adapty.GetPaywall(actionId, (paywall, error) => {
                if (error != null) {
                    // handle the error
                    return;
                }

                AdaptyUI.CreatePaywallView(paywall, (paywallView, createError) => {
                    if (createError != null) {
                        // handle the error
                        return;
                    }

                    paywallView.Present((presentError) => {
                        if (presentError != null) {
                            // handle the error
                        }
                    });
                });
            });
        });
    }
    
    // ... other interface methods
}

{
    "action_id": "premium_offer_1",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "pricing_screen",
        "screen_index": 2,
        "total_screens": 4
    }
}

Finalización de la carga del onboarding

Cuando un onboarding termina de cargarse, implementa el método OnboardingViewDidFinishLoading:

public class OnboardingManager : MonoBehaviour, AdaptyOnboardingsEventsListener
{
    public void OnboardingViewDidFinishLoading(
        AdaptyUIOnboardingView view,
        AdaptyUIOnboardingMeta meta
    )
    {
        // handle loading completion
    }
    
    // ... other interface methods
}

{
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "welcome_screen",
        "screen_index": 0,
        "total_screens": 4
    }
}

Seguimiento de navegación

El método OnboardingViewOnAnalyticsEvent se invoca cuando ocurren distintos eventos de analítica durante el flow de onboarding. El objeto analyticsEvent puede ser de uno de los siguientes tipos:

A continuación se muestra un ejemplo de cómo usar los eventos de analítica para el seguimiento:

public class OnboardingManager : MonoBehaviour, AdaptyOnboardingsEventsListener
{
    public void OnboardingViewOnAnalyticsEvent(
        AdaptyUIOnboardingView view,
        AdaptyUIOnboardingMeta meta,
        AdaptyOnboardingsAnalyticsEvent analyticsEvent
    )
    {
        switch (analyticsEvent) {
            case AdaptyOnboardingsAnalyticsEventOnboardingStarted:
                // track onboarding start
                TrackEvent("onboarding_started", meta);
                break;
            case AdaptyOnboardingsAnalyticsEventScreenPresented:
                // track screen presentation
                TrackEvent("screen_presented", meta);
                break;
            case AdaptyOnboardingsAnalyticsEventScreenCompleted screenCompleted:
                // track screen completion with user response
                TrackEvent("screen_completed", meta, screenCompleted.ElementId, screenCompleted.Reply);
                break;
            case AdaptyOnboardingsAnalyticsEventOnboardingCompleted:
                // track successful onboarding completion
                TrackEvent("onboarding_completed", meta);
                break;
            case AdaptyOnboardingsAnalyticsEventUnknown unknownEvent:
                // handle unknown events
                TrackEvent(unknownEvent.Name, meta);
                break;
            // handle other cases as needed
        }
    }
    
    // ... other interface methods
}

// onboardingStarted
{
  "name": "onboarding_started",
  "meta": {
    "onboarding_id": "onboarding_123",
    "screen_cid": "welcome_screen",
    "screen_index": 0,
    "total_screens": 4
  }
}

// screenPresented

{
    "name": "screen_presented",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "interests_screen",
        "screen_index": 2,
        "total_screens": 4
    }
}

// screenCompleted

{
    "name": "screen_completed",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    },
    "params": {
        "element_id": "profile_form",
        "reply": "success"
    }
}

// secondScreenPresented

{
    "name": "second_screen_presented",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    }
}

// userEmailCollected

{
    "name": "user_email_collected",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "profile_screen",
        "screen_index": 1,
        "total_screens": 4
    }
}

// onboardingCompleted

{
    "name": "onboarding_completed",
    "meta": {
        "onboarding_id": "onboarding_123",
        "screen_cid": "final_screen",
        "screen_index": 3,
        "total_screens": 4
    }
}