문서

Cordova SDK - SDK 메서드 레퍼런스

이 포괄적인 참조 문서에는 Cordova 애플리케이션용 Singular SDK에서 사용 가능한 모든 메소드가 설명되어 있습니다. SDK는 초기화, 사용자 식별, 이벤트 추적, 구매 보고, 어트리뷰션, 데이터 개인정보 보호 규정 준수 및 구성을 위한 기능을 제공합니다. 각 메서드에는 설명, 서명, 실제 사용 예시가 함께 제공되어 개발자가 Singular의 SDK 기능을 애플리케이션에 연동하는 데 도움이 됩니다.

광고 구매

Singular.adRevenue 메서드

자세한 광고 데이터 정보로 광고 구매 이벤트를 추적합니다. 이 메서드를 사용하면 애플리케이션에 표시된 광고에서 발생한 구매을 다양한 파라미터와 함께 보고하여 광고 성과를 분류하고 분석할 수 있습니다.

시그니처

static adRevenue(adData: SingularAdData): void

사용 예시

// 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

Singular.clearGlobalProperties 메서드

이전에 설정된 모든 글로벌 속성을 제거합니다. 사용자가 애플리케이션에서 로그아웃할 때와 같이 전역 속성을 재설정해야 할 때 유용합니다.

서명

static clearGlobalProperties(): void

사용 예시

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

createReferrerShortLink

Singular.createReferrerShortLink 메서드

공유 및 어트리뷰션에 사용할 수 있는 리퍼러 정보가 포함된 짧은 링크를 생성합니다. 이 메서드는 사용자와 공유할 수 있는 추적 가능한 링크를 생성하여 설치 및 활동을 특정 리퍼럴 소스에 어트리뷰션할 수 있도록 합니다.

서명

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

사용 예시

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

Singular.customRevenue 메서드

지정된 이벤트 이름, 통화 및 금액으로 사용자 지정 구매 이벤트를 추적합니다. 이를 통해 보다 구체적인 구매 추적을 위해 사용자 지정 이름으로 구매 이벤트를 추적할 수 있습니다.

참고: 사용자 지정 구매 이벤트 이름은 32개의 ASCII 문자로 제한됩니다. ASCII가 아닌 문자의 경우 UTF-8로 변환하면 32바이트로 제한됩니다.
통화 코드는 모두 대문자이어야 하며 3글자로 구성된 ISO 4217 통화 코드를 준수해야 합니다.

서명

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

사용 예

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

customRevenueWithArgs

Singular.customRevenueWithArgs 메서드

지정된 이벤트 이름, 통화, 금액 및 추가 사용자 지정 속성을 사용하여 사용자 지정 구매 이벤트를 추적합니다. 이를 통해 사용자 지정 매개변수를 사용하여 더 자세한 구매을 추적할 수 있습니다.

참고: 사용자 지정 구매 이벤트 이름은 32개의 ASCII 문자로 제한됩니다. ASCII가 아닌 문자의 경우 UTF-8로 변환하면 32바이트로 제한됩니다.
이벤트 속성 이름과 속성 값은 500자로 제한됩니다.
통화 코드는 모두 대문자이어야 하며 3글자로 구성된 ISO 4217 통화 코드를 준수해야 합니다.

서명

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

사용 예

// 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"
    }
);

event

Singular.event 메서드

지정된 이름의 간단한 이벤트를 추적합니다. 이 메서드를 사용하여 애플리케이션 내에서 사용자 행동과 참여를 추적하세요.

서명

static event(eventName: string): void

사용 예시

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

eventWithArgs

Singular.eventWithArgs 메서드

지정된 이름과 추가 사용자 지정 속성으로 이벤트를 추적합니다. 이를 통해 사용자 정의 매개변수를 사용하여 보다 자세한 이벤트 추적이 가능합니다.

서명

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

사용 예시

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

getGlobalProperties

Singular.getGlobalProperties 메서드

현재 설정된 모든 글로벌 프로퍼티를 검색합니다. 이 메서드는 SDK에 설정된 모든 글로벌 프로퍼티가 포함된 객체를 반환합니다.

서명

static getGlobalProperties(success: Function): void

사용 예제

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

getLimitDataSharing

Singular.getLimitDataSharing 메서드

현재 데이터 공유 제한 상태를 검색합니다. 이 메서드는 현재 데이터 공유가 제한되어 있는지 여부를 나타내는 부울을 반환합니다.

서명

static getLimitDataSharing(success: Function): void

사용 예시

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

핸들 푸시 알림

Singular.handlePushNotification 메서드

어트리뷰션을 위한 푸시 알림 페이로드를 처리합니다. 앱이 푸시 알림을 수신할 때 이 메서드를 호출해야 Singular가 올바르게 어트리뷰션할 수 있습니다.

서명

static handlePushNotification(pushNotificationPayload: Object): void

사용 예시

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

init

Singular.init 메서드

제공된 구성으로 Singular SDK를 초기화합니다. Singular SDK 사용을 시작하기 위해 가장 먼저 호출해야 하는 메서드입니다.

서명

static init(singularConfig: SingularConfig): void

사용 예제

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

Singular.isAllTrackingStopped 메서드

현재 모든 트래킹이 중지되었는지 확인합니다. 이 메서드는 현재 추적이 중지되었는지 여부를 나타내는 부울을 반환합니다.

서명

static isAllTrackingStopped(success: Function): void

사용 예시

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

limitDataSharing

Singular.limitDataSharing 메서드

데이터 공유 제한 상태를 설정합니다. 사용자 동의 또는 개인정보 보호 요구 사항에 따라 데이터 공유를 제한하려면 이 메서드를 사용합니다.

서명

static limitDataSharing(value: boolean): void

사용 예

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

revenue

Singular.revenue 메서드

지정된 통화와 금액으로 구매 이벤트를 추적합니다. 이 메서드는 애플리케이션 내에서 발생한 구매을 보고하는 데 사용됩니다.

통화 코드는 모두 대문자이어야 하며 세 글자로 구성된 ISO 4217 통화 코드를 준수해야 합니다.

서명

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

사용 예

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

revenueWithArgs

Singular.revenueWithArgs 메서드

지정된 통화, 금액 및 추가 사용자 지정 속성을 사용하여 구매 이벤트를 추적합니다. 이를 통해 사용자 지정 매개변수를 사용하여 보다 상세한 구매 추적이 가능합니다.

이벤트 속성 이름과 속성 값은 500자로 제한됩니다.
통화 코드는 모두 대문자이어야 하며 3글자로 구성된 ISO 4217 통화 코드를 준수해야 합니다.

서명

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

사용 예시

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

resumeAllTracking

Singular.resumeAllTracking 메서드

이전에 중지된 모든 추적 활동을 재개합니다. 추적이 중지된 후 다시 활성화하려면 이 메서드를 사용합니다.

서명

static resumeAllTracking(): void

사용 예시

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

setCustomUserId

Singular.setCustomUserId 메서드

현재 사용자에 대한 사용자 지정 사용자 아이디를 설정합니다. 이를 통해 Singular 데이터를 자체 사용자 식별 시스템과 연결할 수 있습니다.

서명

static setCustomUserId(userId: string): void

사용 예시

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

setGlobalProperty

Singular.setGlobalProperty 메서드

모든 이벤트와 함께 전송할 글로벌 프로퍼티를 설정합니다. 이를 통해 매번 속성을 지정하지 않고도 모든 이벤트에 일관된 속성을 추가할 수 있습니다.

서명

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

사용 예시

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

setUninstallToken

Singular.setUninstallToken 메서드

제거 추적을 위한 디바이스 토큰을 설정합니다. 이 메서드는 제거 추적을 활성화하려면 푸시 알림 토큰과 함께 호출해야 합니다.

서명

static setUninstallToken(token: string): void

사용 예시

// 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

Singular.skanGetConversionValue 메서드

현재 SKAdNetwork 전환 값을 가져옵니다. 이 메서드는 iOS에만 적용되며, SKAdNetwork 어트리뷰션에 사용된 현재 전환 값을 반환합니다.

서명

static skanGetConversionValue(success: Function): void

사용 예시

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

skanRegisterAppForAdNetworkAttribution

Singular.skanRegisterAppForAdNetworkAttribution 메서드

앱을 SKAdNetwork 어트리뷰션에 등록합니다. 이 메서드는 iOS에만 해당되며, SKAdNetwork 어트리뷰션을 활성화하기 위해 호출해야 합니다.

서명

static skanRegisterAppForAdNetworkAttribution(): void

사용 예시

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

skanUpdateConversionValue

Singular.skanUpdateConversionValue 메서드

SKAdNetwork 전환 값을 업데이트합니다. 이 메서드는 iOS 전용으로, SKAdNetwork 어트리뷰션에 사용되는 전환 값을 수동으로 업데이트할 수 있습니다.

서명

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

사용 예시

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

skanUpdateConversionValues

Singular.skanUpdateConversionValues 메서드

추가 파라미터로 SKAdNetwork 전환 값을 업데이트합니다. 이 메서드는 iOS 16.1 이상에만 적용되며, SKAdNetwork 4.0 어트리뷰션의 미세, 거친, 잠금 값을 업데이트할 수 있습니다.

서명

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

사용 예시

// 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

Singular.stopAllTracking 메서드

모든 추적 활동을 중지합니다. 이 메서드를 사용하면 사용자가 옵트아웃할 때 또는 개인 정보 보호를 준수하기 위해 추적을 비활성화할 수 있습니다.

서명

static stopAllTracking(): void

사용 예시

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

trackingOptIn

Singular.trackingOptIn 메서드

사용자가 추적에 옵트인했음을 나타냅니다. 사용자가 추적 및 데이터 수집에 명시적으로 동의할 때 이 메서드를 호출합니다.

서명

static trackingOptIn(): void

사용 예시

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

trackingUnder13

Singular.trackingUnder13 메서드

사용자가 13세 미만임을 나타냅니다. 이 메서드를 호출하면 13세 미만 사용자에 대한 COPPA 및 기타 규정을 준수할 수 있습니다.

서명

static trackingUnder13(): void

사용 예시

// 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

Singular.unsetCustomUserId 메서드

이전에 설정된 사용자 지정 사용자 아이디를 제거합니다. 사용자가 로그아웃하거나 이벤트를 더 이상 현재 사용자 ID에 연결하지 않으려는 경우 이 메서드를 호출하세요.

서명

static unsetCustomUserId(): void

사용 예시

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

unsetGlobalProperty

Singular.unsetGlobalProperty 메서드

이전에 설정된 전역 속성을 제거합니다. 특정 글로벌 프로퍼티를 더 이상 이벤트와 함께 전송하지 않으려면 이 메서드를 호출하세요.

서명

static unsetGlobalProperty(key: string): void

사용 예시

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

Cordova SDK - SDK 메서드 참조

Cordova SDK - SDK 메서드 레퍼런스

광고 구매

Singular.adRevenue 메서드

시그니처

사용 예시

clearGlobalProperties

Singular.clearGlobalProperties 메서드

서명

사용 예시

createReferrerShortLink

Singular.createReferrerShortLink 메서드

서명

사용 예시

customRevenue

Singular.customRevenue 메서드

서명

사용 예

customRevenueWithArgs

Singular.customRevenueWithArgs 메서드

서명

사용 예

event

Singular.event 메서드

서명

사용 예시

eventWithArgs

Singular.eventWithArgs 메서드

서명

사용 예시

getGlobalProperties

Singular.getGlobalProperties 메서드

서명

사용 예제

getLimitDataSharing

Singular.getLimitDataSharing 메서드

서명

사용 예시

핸들 푸시 알림

Singular.handlePushNotification 메서드

서명

사용 예시

init

Singular.init 메서드

서명

사용 예제

isAllTrackingStopped

Singular.isAllTrackingStopped 메서드

서명

사용 예시

limitDataSharing

Singular.limitDataSharing 메서드

서명

사용 예

revenue

Singular.revenue 메서드

서명

사용 예

revenueWithArgs

Singular.revenueWithArgs 메서드

서명

사용 예시

resumeAllTracking

Singular.resumeAllTracking 메서드

서명

사용 예시

setCustomUserId

Singular.setCustomUserId 메서드

서명

사용 예시

setGlobalProperty

Singular.setGlobalProperty 메서드

서명

사용 예시

setUninstallToken

Singular.setUninstallToken 메서드

서명

사용 예시

skanGetConversionValue

Singular.skanGetConversionValue 메서드