Documento SDK para iOS - Opciones avanzadas

Opciones avanzadas

Configure las funciones avanzadas del SDK, incluida la gestión de sesiones y la integración de JavaScript para aplicaciones híbridas basadas en WKWebView.

Gestión de sesiones

Gestión automática de sesiones

El SDK de Singular gestiona automáticamente la sesión sin necesidad de configuración adicional para aplicaciones iOS modernas.

Comportamiento por defecto:

Cuando la app pasa a segundo plano durante 60 segundos o más, el SDK registra una nueva sesión al volver al primer plano.

Configuración del tiempo de espera de la sesión

Personalice la duración del tiempo de espera de la sesión para adaptarla a los patrones de uso de su aplicación.

Firma del método:

+ (void)setSessionTimeout:(int)timeoutInSeconds;

// Initialize SDK configuration
guard let config = SingularConfig(
    apiKey: "SDK_KEY",
    andSecret: "SDK_SECRET"
) else {
    return
}

// Set session timeout to 120 seconds (2 minutes)
Singular.setSessionTimeout(120)

// Start the SDK
Singular.start(config)

// Initialize SDK configuration
SingularConfig *config = [[SingularConfig alloc] 
    initWithApiKey:@"SDK_KEY" 
    andSecret:@"SDK_SECRET"];

// Set session timeout to 120 seconds (2 minutes)
[Singular setSessionTimeout:120];

// Start the SDK
[Singular start:config];

Timeout Valores:

Predeterminado: 60 segundos
Mínimo: 0 segundos (cada transición fondo/primer plano crea una nueva sesión)
Recomendado: 30-180 segundos dependiendo de los patrones de uso de la aplicación

Práctica recomendada: Llame a setSessionTimeoutantes de llamar a Singular.start() para asegurarse de que el valor del tiempo de espera se aplica desde la primera sesión.

Interfaz JavaScript para aplicaciones híbridas

Visión general

Habilite la funcionalidad de Singular SDK desde código JavaScript en aplicaciones híbridas basadas en WKWebView utilizando la interfaz JavaScript.

Métodos admitidos:

setCustomUserId: Establece el identificador de usuario personalizado
unsetCustomUserId: Elimina el identificador de usuario personalizado
event: Seguimiento de eventos con o sin atributos
ingresos: Seguimiento de ingresos

Configuración de la integración WKWebView

Configure la interfaz JavaScript en el WKNavigationDelegate de su controlador de vista para habilitar los métodos de Singular SDK desde JavaScript.

Nota: A partir de iOS 8.0, Apple recomienda utilizar WKWebView para añadir contenido web a su aplicación. No utilice UIWebView ni WebView. Consulte la documentación de WKWebView de Applepara obtener más información.

import UIKit
import WebKit

class ViewController: UIViewController {
    
    var webView: WKWebView!
    
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Create WKWebView
        let webConfiguration = WKWebViewConfiguration()
        webView = WKWebView(frame: .zero, configuration: webConfiguration)
        webView.navigationDelegate = self
        view.addSubview(webView)
        
        // Load web content
        if let url = Bundle.main.url(forResource: "index", withExtension: "html") {
            webView.loadFileURL(url, allowingReadAccessTo: url)
        }
    }
}

extension ViewController: WKNavigationDelegate {
    
    func webView(_ webView: WKWebView,
                decidePolicyFor navigationAction: WKNavigationAction,
                decisionHandler: @escaping (WKNavigationActionPolicy) -> Void) {
        
        // Check if Singular JavaScript interface exists
        let js = "typeof(Singular)"
        webView.evaluateJavaScript(js) { (result, error) -> Void in
            if let resultString = result as? String {
                if resultString == "undefined" {
                    // Load Singular JavaScript interface
                    do {
                        if let path = Bundle.main.path(forResource: "Singular", ofType: "js") {
                            let contents = try String(contentsOfFile: path)
                            webView.evaluateJavaScript(contents, completionHandler: nil)
                        }
                    } catch {
                        print("Error loading Singular.js: \(error)")
                    }
                } else {
                    // Process Singular SDK request
                    Singular.processJSRequestWK(webView, withURL: navigationAction.request)
                }
            }
        }
        
        // Allow navigation
        decisionHandler(.allow)
    }
}

#import <UIKit/UIKit.h>
#import <WebKit/WebKit.h>
#import <Singular/Singular.h>

@interface ViewController () <WKNavigationDelegate>
@property (strong, nonatomic) WKWebView *webView;
@end

@implementation ViewController

- (void)viewDidLoad {
    [super viewDidLoad];
    
    // Create WKWebView
    WKWebViewConfiguration *webConfiguration = [[WKWebViewConfiguration alloc] init];
    self.webView = [[WKWebView alloc] initWithFrame:CGRectZero configuration:webConfiguration];
    self.webView.navigationDelegate = self;
    [self.view addSubview:self.webView];
    
    // Load web content
    NSURL *url = [[NSBundle mainBundle] URLForResource:@"index" withExtension:@"html"];
    if (url) {
        [self.webView loadFileURL:url allowingReadAccessToURL:url];
    }
}

- (void)webView:(WKWebView *)webView
    decidePolicyForNavigationAction:(WKNavigationAction *)navigationAction
    decisionHandler:(void (^)(WKNavigationActionPolicy))decisionHandler {
    
    // Check if Singular JavaScript interface exists
    NSString *js = @"typeof(Singular)";
    [webView evaluateJavaScript:js completionHandler:^(id result, NSError *error) {
        if ([result isKindOfClass:[NSString class]]) {
            NSString *resultString = (NSString *)result;
            if ([resultString isEqualToString:@"undefined"]) {
                // Load Singular JavaScript interface
                NSString *path = [[NSBundle mainBundle] pathForResource:@"Singular" ofType:@"js"];
                if (path) {
                    NSError *readError;
                    NSString *contents = [NSString stringWithContentsOfFile:path 
                        encoding:NSUTF8StringEncoding 
                        error:&readError];
                    if (contents) {
                        [webView evaluateJavaScript:contents completionHandler:nil];
                    } else {
                        NSLog(@"Error loading Singular.js: %@", readError);
                    }
                }
            } else {
                // Process Singular SDK request
                [Singular processJSRequestWK:webView withURL:navigationAction.request];
            }
        }
    }];
    
    // Allow navigation
    decisionHandler(WKNavigationActionPolicyAllow);
}

@end

Requisitos de instalación:

Incluya el archivo Singular.js en el paquete de su aplicación.
Establece tu controlador de vista como delegado de navegación del WKWebView
Implementar el método delegado decidePolicyForNavigationAction
Llame a processJSRequestWK para gestionar las solicitudes de Singular SDK

Uso de JavaScript

Llame a los métodos de Singular desde el código JavaScript que se ejecuta en su WKWebView.

Seguimiento de eventos

// Simple event without attributes
Singular.event('level_completed');

// Event with attributes (pass as JSON string)
Singular.event('purchase_attempt', 
    JSON.stringify({
        "item_name": "sword",
        "item_category": "weapons",
        "item_price": 9.99
    })
);

Seguimiento de ingresos

// Track revenue in USD
Singular.revenue('USD', 9.99);

// Track revenue in other currencies
Singular.revenue('EUR', 8.50);

Gestión de ID de usuario personalizados

// Set custom user ID
Singular.setCustomUserId('user_12345');

// Remove custom user ID
Singular.unsetCustomUserId();

Notas sobre la API de JavaScript:

Todos los métodos se invocan en el objeto global Singular
Los atributos de evento deben pasarse como objetos JSON-stringified
Los nombres de los métodos utilizan camelCase (por ejemplo, setCustomUserId)
La interfaz conecta automáticamente las llamadas de JavaScript con los métodos nativos del SDK.

SDK de iOS - Opciones avanzadas

Opciones avanzadas

Gestión de sesiones

Gestión automática de sesiones

Configuración del tiempo de espera de la sesión

Interfaz JavaScript para aplicaciones híbridas

Visión general

Configuración de la integración WKWebView

Uso de JavaScript

Seguimiento de eventos

Seguimiento de ingresos

Gestión de ID de usuario personalizados