SDK do Cordova - Referência dos métodos do SDK

Seguir
Avatar
Jared Ornstead
Updated
Documento de referência

SDK do Cordova - Referência de métodos do SDK

Esta referência abrangente documenta todos os métodos disponíveis no SDK da Singular para aplicações Cordova. O SDK fornece funcionalidade para inicialização, identificação do usuário, rastreamento de eventos, relatórios de receita, atribuição, conformidade com a privacidade de dados e configuração. Cada método é apresentado com uma descrição, assinatura e exemplos práticos de uso para ajudar os desenvolvedores a integrar os recursos do SDK da Singular em seus aplicativos.

adRevenue

Método Singular.adRevenue

Rastreia eventos de receita de anúncios com informações detalhadas de dados de anúncios. Este método permite-lhe reportar as receitas geradas pelos anúncios apresentados na sua aplicação com vários parâmetros para categorizar e analisar o desempenho do anúncio.

Assinatura

static adRevenue(adData: SingularAdData): void

Exemplo de utilização

javascript
// Create ad data object
const adData = new cordova.plugins.SingularCordovaSdk.SingularAdData()
    .withAdPlatform("AdMob")
    .withAdType("Rewarded")
    .withNetworkName("Google")
    .withCurrency("USD")
    .withRevenue(0.05);

// Track ad revenue event
cordova.plugins.SingularCordovaSdk.adRevenue(adData);

clearGlobalProperties

Método Singular.clearGlobalProperties

Remove todas as propriedades globais definidas anteriormente. Isto é útil quando é necessário repor as propriedades globais, por exemplo, quando um utilizador termina a sessão na sua aplicação.

Assinatura

static clearGlobalProperties(): void

Exemplo de utilização

javascript
// Clear all global properties, for example when a user logs out
cordova.plugins.SingularCordovaSdk.clearGlobalProperties();

createReferrerShortLink

Método Singular.createReferrerShortLink

Cria um link curto com informações do referenciador que podem ser usadas para compartilhamento e atribuição. Este método gera links rastreáveis que podem ser partilhados com os utilizadores, permitindo-lhe atribuir instalações e actividades a fontes de referência específicas.

Assinatura

static createReferrerShortLink(url: string, refName: string, refId: string, passthroughParams: Object, resultHandler: Object): void

Exemplo de utilização

javascript
cordova.plugins.SingularCordovaSdk.createReferrerShortLink(
    "https://sample.sng.link/B4tbm/v8fp?_dl=https%3A%2F%2Fabc.com",
    "John Doe", // Referrer Name
    "aq239897", // Referrer ID
    { 
        "channel": "sms", 
        "campaign": "summer_promo" 
    }, // Passthrough parameters
    {
        onSuccess: function(shortLinkURL) {
            console.log("Generated short link:", shortLinkURL);
            // Share the link with users
        },
        onError: function(error) {
            console.error("Error creating short link:", error);
        }
    }
);

customRevenue

Método Singular.customRevenue

Rastreia um evento de receita personalizado com um nome de evento, moeda e valor especificados. Isso permite rastrear eventos de receita com nomes personalizados para um rastreamento de receita mais específico.

  • Nota: Os nomes de eventos de receita personalizados são limitados a 32 caracteres ASCII. Para caracteres não ASCII, o limite é de 32 bytes depois de convertidos para UTF-8.
  • Os códigos de moeda devem estar em MAIÚSCULAS e seguir o código de moeda ISO 4217 de três letras.

Assinatura

static customRevenue(eventName: string, currency: string, amount: number): void

Exemplo de utilização

javascript
// Track a custom revenue event
cordova.plugins.SingularCordovaSdk.customRevenue("premium_subscription", "USD", 9.99);

customRevenueWithArgs

Método Singular.customRevenueWithArgs

Rastreia um evento de receita personalizado com um nome de evento, moeda, montante e atributos personalizados adicionais especificados. Isso permite um rastreamento de receita mais detalhado com parâmetros personalizados.

  • Nota: Os nomes de eventos de receita personalizados estão limitados a 32 caracteres ASCII. Para caracteres não-ASCII, o limite é de 32 bytes depois de convertidos para UTF-8.
  • Os nomes e valores de atributos de eventos estão limitados a 500 caracteres ASCII.
  • Os códigos de moeda devem estar em MAIÚSCULAS e respeitar o código de moeda ISO 4217 de três letras.

Assinatura

static customRevenueWithArgs(eventName: string, currency: string, amount: number, args: Object): void

Exemplo de utilização

javascript
// Track a custom revenue event with additional parameters
cordova.plugins.SingularCordovaSdk.customRevenueWithArgs(
    "in_app_purchase",
    "USD",
    5.99,
    {
        "product_id": "com.app.gems_pack_small",
        "quantity": 1,
        "transaction_id": "T12345678",
        "receipt_id": "R98765432"
    }
);

evento

Método Singular.event

Rastreia um evento simples com o nome especificado. Utilize este método para acompanhar as acções e o envolvimento do utilizador na sua aplicação.

Assinatura

static event(eventName: string): void

Exemplo de utilização

javascript
// Track a simple event
cordova.plugins.SingularCordovaSdk.event("level_completed");

eventWithArgs

Método Singular.eventWithArgs

Rastreia um evento com o nome especificado e atributos personalizados adicionais. Isto permite um seguimento mais detalhado do evento com parâmetros personalizados.

Assinatura

static eventWithArgs(eventName: string, args: Object): void

Exemplo de utilização

javascript
// Track an event with additional parameters
cordova.plugins.SingularCordovaSdk.eventWithArgs(
    "level_completed",
    {
        "level_id": 5,
        "score": 12500,
        "time_spent": 120,
        "difficulty": "medium"
    }
);

getGlobalProperties

Método Singular.getGlobalProperties

Recupera todas as propriedades globais atualmente definidas. Este método devolve um objeto que contém todas as propriedades globais que foram definidas para o SDK.

Assinatura

static getGlobalProperties(success: Function): void

Exemplo de utilização

javascript
// Get all global properties
cordova.plugins.SingularCordovaSdk.getGlobalProperties(function(properties) {
    console.log("Current global properties:", properties);
});

getLimitDataSharing

Método Singular.getLimitDataSharing

Recupera o estado atual da limitação da partilha de dados. Este método devolve um booleano que indica se a partilha de dados está atualmente limitada.

Assinatura

static getLimitDataSharing(success: Function): void

Exemplo de utilização

javascript
// Check if data sharing is limited
cordova.plugins.SingularCordovaSdk.getLimitDataSharing(function(isLimited) {
    console.log("Data sharing is limited:", isLimited);
});

handlePushNotification

Método Singular.handlePushNotification

Processa uma carga útil de notificação push para atribuição. Este método deve ser chamado quando seu aplicativo recebe uma notificação push para permitir que o Singular a atribua corretamente.

Assinatura

static handlePushNotification(pushNotificationPayload: Object): void

Exemplo de uso

javascript
// Handle a received push notification
document.addEventListener('push-notification', function(event) {
    var notification = event.notification;
    cordova.plugins.SingularCordovaSdk.handlePushNotification(notification);
}, false);

init

Método Singular.init

Inicializa o Singular SDK com a configuração fornecida. Este é o primeiro método que você deve chamar para começar a usar o Singular SDK.

Assinatura

static init(singularConfig: SingularConfig): void

Exemplo de uso

javascript
document.addEventListener('deviceready', function() {
    // Create configuration object
    var singularConfig = new cordova.plugins.SingularCordovaSdk.SingularConfig(
        "SDK KEY", 
        "SDK SECRET"
    );
    
    // Initialize the SDK
    cordova.plugins.SingularCordovaSdk.init(singularConfig);
}, false);

isAllTrackingStopped

Método Singular.isAllTrackingStopped

Verifica se todo o rastreamento está parado no momento. Este método devolve um booleano que indica se o rastreio está atualmente parado.

Assinatura

static isAllTrackingStopped(success: Function): void

Exemplo de utilização

javascript
// Check if tracking is stopped
cordova.plugins.SingularCordovaSdk.isAllTrackingStopped(function(isStopped) {
    console.log("Tracking is stopped:", isStopped);
});

limitDataSharing

Método Singular.limitDataSharing

Define o estado de limitação da partilha de dados. Utilize este método para limitar a partilha de dados com base no consentimento do utilizador ou em requisitos de privacidade.

Assinatura

static limitDataSharing(value: boolean): void

Exemplo de utilização

javascript
// Limit data sharing based on user consent
function onUserConsentChanged(hasConsent) {
    cordova.plugins.SingularCordovaSdk.limitDataSharing(!hasConsent);
}

revenue

Método Singular.revenue

Rastreia um evento de receita com a moeda e o montante especificados. Este método é utilizado para comunicar receitas geradas na sua aplicação.

Assinatura

static revenue(currency: string, amount: number): void

Exemplo de utilização

javascript
// Track a revenue event
cordova.plugins.SingularCordovaSdk.revenue("USD", 4.99);

revenueWithArgs

Método Singular.revenueWithArgs

Rastreia um evento de receita com a moeda, o montante e os atributos personalizados adicionais especificados. Isto permite um controlo mais detalhado das receitas com parâmetros personalizados.

  • Os nomes e valores dos atributos do evento estão limitados a 500 caracteres ASCII.
  • Os códigos de moeda têm de estar em MAIÚSCULAS e respeitar o código de moeda ISO 4217 de três letras.

Assinatura

static revenueWithArgs(currency: string, amount: number, args: Object): void

Exemplo de utilização

javascript
// Track a revenue event with additional parameters
cordova.plugins.SingularCordovaSdk.revenueWithArgs(
    "USD",
    4.99,
    {
        "product_id": "com.app.premium_upgrade",
        "transaction_id": "T12345678"
    }
);

resumeAllTracking

Método Singular.resumeAllTracking

Retoma todas as actividades de seguimento que foram anteriormente interrompidas. Utilize este método para reativar o seguimento depois de este ter sido interrompido.

Assinatura

static resumeAllTracking(): void

Exemplo de utilização

javascript
// Resume tracking, for example when user opts back in
function onUserOptIn() {
    cordova.plugins.SingularCordovaSdk.resumeAllTracking();
}

setCustomUserId

Método Singular.setCustomUserId

Define um ID de usuário personalizado para o usuário atual. Isto permite-lhe associar os dados Singular ao seu próprio sistema de identificação de utilizadores.

Assinatura

static setCustomUserId(userId: string): void

Exemplo de uso

javascript
// Set custom user ID after user logs in
function onUserLogin(userId) {
    cordova.plugins.SingularCordovaSdk.setCustomUserId(userId);
}

setGlobalProperty

Método Singular.setGlobalProperty

Define uma propriedade global que será enviada com todos os eventos. Isto permite-lhe adicionar atributos consistentes a todos os eventos sem os especificar de cada vez.

Assinatura

static setGlobalProperty(key: string, value: string, overrideExisting: boolean, success: Function): void

Exemplo de uso

javascript
// Set a global property
cordova.plugins.SingularCordovaSdk.setGlobalProperty(
    "user_tier", 
    "premium", 
    true, 
    function(isSuccess) {
        console.log("Global property set successfully:", isSuccess);
    }
);

setUninstallToken

Método Singular.setUninstallToken

Define o token do dispositivo para rastreamento de desinstalação. Este método deve ser chamado com o token de notificação push para ativar o rastreio de desinstalação.

Assinatura

static setUninstallToken(token: string): void

Exemplo de utilização

javascript
// Set uninstall token when push token is received
document.addEventListener('push-registration', function(event) {
    var token = event.registrationId;
    cordova.plugins.SingularCordovaSdk.setUninstallToken(token);
}, false);

skanGetConversionValue

Método Singular.skanGetConversionValue

Recupera o valor de conversão atual de SKAdNetwork. Este método é específico do iOS e devolve o valor de conversão atual utilizado para a atribuição de SKAdNetwork.

Assinatura

static skanGetConversionValue(success: Function): void

Exemplo de utilização

javascript
// Get the current SKAdNetwork conversion value
cordova.plugins.SingularCordovaSdk.skanGetConversionValue(function(conversionValue) {
    console.log("Current conversion value:", conversionValue);
});

skanRegisterAppForAdNetworkAttribution

Método Singular.skanRegisterAppForAdNetworkAttribution

Regista a aplicação para atribuição de SKAdNetwork. Este método é específico do iOS e deve ser chamado para ativar a atribuição de SKAdNetwork.

Assinatura

static skanRegisterAppForAdNetworkAttribution(): void

Exemplo de utilização

javascript
// Register for SKAdNetwork attribution
if (device.platform === 'iOS') {
    cordova.plugins.SingularCordovaSdk.skanRegisterAppForAdNetworkAttribution();
}

skanUpdateConversionValue

Método Singular.skanUpdateConversionValue

Actualiza o valor de conversão de SKAdNetwork. Este método é específico do iOS e permite-lhe atualizar manualmente o valor de conversão utilizado para a atribuição de SKAdNetwork.

Assinatura

static skanUpdateConversionValue(value: number, success: Function): void

Exemplo de utilização

javascript
// Update the SKAdNetwork conversion value
if (device.platform === 'iOS') {
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValue(5, function(isSuccess) {
        console.log("Conversion value updated successfully:", isSuccess);
    });
}

skanUpdateConversionValues

Método Singular.skanUpdateConversionValues

Actualiza os valores de conversão de SKAdNetwork com parâmetros adicionais. Este método é específico do iOS 16.1+ e permite-lhe atualizar os valores finos, grossos e de bloqueio para atribuição de SKAdNetwork 4.0.

Assinatura

static skanUpdateConversionValues(value: number, coarse: string, lock: boolean, success: Function): void

Exemplo de utilização

javascript
// Update the SKAdNetwork 4.0 conversion values
if (device.platform === 'iOS') {
    cordova.plugins.SingularCordovaSdk.skanUpdateConversionValues(
        5,           // fine value (0-63)
        "medium",    // coarse value (low/medium/high)
        false,       // lock
        function(isSuccess) {
            console.log("Conversion values updated successfully:", isSuccess);
        }
    );
}

stopAllTracking

Método Singular.stopAllTracking

Interrompe todas as actividades de rastreio. Utilize este método para desativar o rastreio quando os utilizadores optam por não o fazer ou para garantir a conformidade com a privacidade.

Assinatura

static stopAllTracking(): void

Exemplo de utilização

javascript
// Stop tracking, for example when user opts out
function onUserOptOut() {
    cordova.plugins.SingularCordovaSdk.stopAllTracking();
}

trackingOptIn

Método Singular.trackingOptIn

Indica que o utilizador optou por aceitar o rastreio. Chame este método quando o utilizador consentir explicitamente no rastreio e na recolha de dados.

Assinatura

static trackingOptIn(): void

Exemplo de utilização

javascript
// User has opted in to tracking
function onUserConsentGiven() {
    cordova.plugins.SingularCordovaSdk.trackingOptIn();
}

trackingUnder13

Método Singular.trackingUnder13

Indica que o utilizador tem menos de 13 anos de idade. Chame este método para cumprir a COPPA e outros regulamentos para utilizadores com menos de 13 anos.

Assinatura

static trackingUnder13(): void

Exemplo de utilização

javascript
// If user is determined to be under 13 years old
cordova.plugins.SingularCordovaSdk.trackingunder13();
console.log("User marked as under 13, GDPR_UNDER_13 flag applied");

unsetCustomUserId

Método Singular.unsetCustomUserId

Remove o ID de utilizador personalizado definido anteriormente. Chame este método quando o utilizador terminar a sessão ou quando já não pretender associar eventos ao ID de utilizador atual.

Assinatura

static unsetCustomUserId(): void

Exemplo de utilização

javascript
// Clear custom user ID when user logs out
function onUserLogout() {
    cordova.plugins.SingularCordovaSdk.unsetCustomUserId();
}

unsetGlobalProperty

Método Singular.unsetGlobalProperty

Remove uma propriedade global previamente definida. Chame este método quando já não quiser que uma propriedade global específica seja enviada com eventos.

Assinatura

static unsetGlobalProperty(key: string): void

Exemplo de uso

javascript
// Remove a global property
cordova.plugins.SingularCordovaSdk.unsetGlobalProperty("user_tier");