🔥 Truy cập đầy đủ Tenjin với giá $200/tháng — bao gồm tất cả tính năng, không cần gói bổ sung, hủy bất cứ lúc nào. Xem giá cả & tính năng

Đăng ký
Xem danh mục

Bộ công cụ phát triển phần mềm (SDK) Mobile Measurement Partner (MMP) dành cho Unity

Thời gian đọc: 30 phút

Tích hợp bằng cách sử dụng các mô hình ngôn ngữ lớn (LLMs) (AI) – Sử dụng lời nhắc sau:

Thêm Tenjin SDK vào dự án của tôi bằng cách sử dụng: https://raw.githubusercontent.com/tenjin/sdk-llm-guides/main/guides/unity/llm-guide.md

Tóm tắt #

Tài liệu dưới đây giới thiệu về SDK Unity dành cho Tenjin. Để tìm hiểu thêm về Tenjin và các sản phẩm của chúng tôi, vui lòng truy cập https://www.tenjin.com.

  • Vui lòng tham khảo Ghi chú phát hành của chúng tôi để xem lịch sử các thay đổi chi tiết theo từng phiên bản.
  • Tenjin Unity SDK hỗ trợ cả hai chế độ iOS và Android.
  • Hãy xem lại tài liệu hướng dẫn về iOS và Android, đồng thời áp dụng các cài đặt nền tảng phù hợp cho các bản dựng của bạn. (iOS, Android)
  • Nếu có bất kỳ vấn đề nào hoặc cần hỗ trợ, vui lòng liên hệ: support@tenjin.com.

Nếu bạn đang sử dụng Unity SDK phiên bản 1.12.29 hoặc thấp hơn, vui lòng làm theo hướng dẫn tại các bước này trước khi hoàn tất việc tích hợp SDK.

Để nâng cấp lên phiên bản 1.12.30 hoặc cao hơn từ các phiên bản thấp hơn, vui lòng đảm bảo gỡ bỏ các tệp nhị phân Tenjin trước khi cài đặt phiên bản Unity mới nhất.

Nếu bạn gặp lỗi này khi biên dịch trên iOS: Thư viện chưa được tải: @rpath/TenjinSDK.framework/TenjinSDK bạn cần vào mục “Frameworks, Libraries and Embedded Content” và thêm TenjinSDK, sau đó chọn ‘Embed & Sign’

Nếu bạn có libTenjinSDK.a và/hoặc libTenjinSDKUniversal.a từ các phiên bản Tenjin SDK cũ hơn, vui lòng xóa chúng và chạy pod Install để tích hợp vào iOS

Trình quản lý gói Unity (UPM) #

Để cài đặt gói UPM từ một URL Git:

  1. Mở cửa sổ Trình quản lý gói, nếu cửa sổ này chưa được mở.
  2. Mở menu Thêm (+) trên thanh công cụ của Trình quản lý gói.
  3. Chọn Cài đặt gói từ URL git trong menu Cài đặt. Một hộp văn bản và nút Cài đặt sẽ xuất hiện.
  4. Hãy nhập URL Git hợp lệ sau đây vào ô văn bản (bạn phải thêm # vào cuối, kèm theo thẻ phiên bản): https://github.com/tenjin/tenjin-unity-sdk.git#1.16.5
  5. Nhấp vào Cài đặt.

Cài đặt thủ công (.unitypackage) #

  1. Tải xuống phiên bản mới nhất của Unity SDK từ đây.
  2. Nhập TenjinUnityPackage.unitypackage vào dự án của bạn: Assets -> Import Package.

Lưu ý quan trọng dành cho Android #

Để đảm bảo Tenjin hoạt động trơn tru với các tính năng và bản sửa lỗi mới nhất, vui lòng đảm bảo các phụ thuộc Maven (Gradle) của bạn đã được cập nhật, vì chúng tôi phân phối SDK Tenjin Android thông qua Maven. Chúng tôi nhận thấy một số nhà phát triển vẫn đang sử dụng các phiên bản lỗi thời, điều này có thể gây ra sự cố.

Nếu bạn biên dịch thông qua Android Studio, vui lòng đảm bảo chạy lệnh Gradle sync để cập nhật các phụ thuộc.

Nếu bạn không sử dụng Android Studio, vui lòng cập nhật các thư viện phụ thuộc trong Unity bằng cách thực hiện theo các bước sau:

  • Mở Unity.
  • Chuyển đến mục Tài sản > Trình quản lý phụ thuộc bên ngoài > Trình giải quyết Android.
  • Chọn “Force Resolve” để cập nhật các phụ thuộc Gradle của bạn lên các phiên bản mới nhất.

Google Play #

Theo mặc định, unspecified là App Store mặc định. Hãy cập nhật giá trị App Store thành googleplay nếu bạn phân phối ứng dụng của mình trên Google Play Store.

Hãy đặt giá trị “Loại App Store” thành googleplay:

C#
BaseTenjin instance = Tenjin.getInstance("");

instance.SetAppStoreType(AppStoreType.googleplay);

Tenjin SDK yêu cầu các quyền sau:

XML
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" /> <!-- Required to get network connectivity (i.e. wifi vs. mobile) -->

Google Play Services yêu cầu tất cả các ứng dụng ở cấp API 32 (Android 13) sử dụng advertising_id (Android Advertising ID (AAID)) phải khai báo quyền AD_ID của Google Play Services (như được hiển thị bên dưới) trong tệp manifest của ứng dụng. Bạn cần cập nhật tenjin-android-sdk lên phiên bản 1.12.8 để có thể sử dụng quyền này.

XML
<uses-permission android:name="com.google.android.gms.permission.AD_ID"/>

Mã nhận dạng quảng cáo Android (AAID) và Nguồn giới thiệu cài đặt #

Thêm ID quảng cáo Android (AAID) và Install Referrer, sau đó thêm chúng vào tệp build.gradle của bạn.

Java
dependencies {
  implementation 'com.google.android.gms:play-services-ads-identifier:{version}'
  implementation 'com.android.installreferrer:installreferrer:{version}'
}

Để có thể thu thập thông tin nguồn giới thiệu cài đặt của Meta, hãy thêm các truy vấn sau vào tệp Android Manifest của bạn:

XML
<queries>
  <package android:name="com.facebook.katana" />
</queries>

<queries>
  <package android:name="com.instagram.android" />
</queries>

Tiếp theo, hãy thêm nội dung sau vào tệp strings.xml của bạn (bạn có thể tạo tệp mẫu này để lưu trữ các giá trị chuỗi dựa trên hướng dẫn này):

XML
<string name="facebook_app_id" translatable="false">YOUR_META_APP_ID</string>

Cửa hàng Amazon #

Theo mặc định, không xác định là App Store mặc định. Hãy cập nhật giá trị App Store thành amazon, nếu bạn phân phối ứng dụng của mình trên cửa hàng Amazon.

Hãy đặt giá trị “Loại App Store” thành amazon:

C#
BaseTenjin instance = Tenjin.getInstance("");

instance.SetAppStoreType(AppStoreType.amazon);

OAID và các cửa hàng ứng dụng Android khác #

Tenjin hỗ trợ việc quảng bá ứng dụng của bạn trên các cửa hàng ứng dụng Android khác thông qua mã OAID của Android. Chúng tôi có các yêu cầu sau đây đối với việc tích hợp các thư viện OAID. Nếu bạn có kế hoạch phát hành ứng dụng của mình ngoài Google Play, hãy đảm bảo triển khai các thư viện OAID này.

MSA OAID #

MSA OAID là mã nhận dạng quảng cáo dành cho các thiết bị được sản xuất tại Trung Quốc do MSA (Liên minh An ninh Di động) cung cấp. Để tích hợp với thư viện MSA, hãy tải xuống tệp sau oaid\_sdk\_1.0.25.aar.

Đặt tệp oaid_sdk_1.0.25.aar vào thư mục Android libs của dự án: /Assets/Plugins/Android

Hãy đặt giá trị “Loại App Store” thành other:

C#
BaseTenjin instance = Tenjin.getInstance("");

instance.SetAppStoreType(AppStoreType.other);

Huawei OAID #

Đối với các khu vực bên ngoài Trung Quốc, bạn có thể thu thập OAID bằng cách sử dụng thư viện do Huawei cung cấp. Để tích hợp với thư viện OAID của Huawei, hãy tải xuống tệp AAR của Huawei sau đây: huawei-ads-identifier.aar. Nếu ứng dụng của bạn có trên Huawei App Gallery, hãy tải xuống và thêm tệp Huawei Install Referrer: huawei-ads-installreferrer.aar.

Hãy đặt các tệp của Huawei vào thư mục Android libs của dự án: /Assets/Plugins/Android

Hãy đặt giá trị “Loại App Store” thành other:

C#
BaseTenjin instance = Tenjin.getInstance("");

instance.SetAppStoreType(AppStoreType.other);

Cài đặt Proguard #

Java
-keep class com.tenjin.** { *; }
-keep public class com.google.android.gms.ads.identifier.** { *; }
-keep public class com.google.android.gms.common.** { *; }
-keep public class com.android.installreferrer.** { *; }
-keep class * extends java.util.ListResourceBundle {
    protected java.lang.Object[][] getContents();
}
-keepattributes *Annotation*

Nếu bạn đang sử dụng các thư viện của Huawei, bạn có thể sử dụng các cài đặt sau:

Java
-keep class com.huawei.hms.ads.** { *; }
-keep interface com.huawei.hms.ads.** { *; }

Khởi tạo ứng dụng #

  1. Hãy lấy SDK_KEY từ trang ứng dụng của bạn. Lưu ý: SDK_KEY là duy nhất cho mỗi ứng dụng của bạn. Bạn có thể tạo tối đa 3 khóa cho cùng một ứng dụng.
app_api_key.png
  1. Trong phương thức Start() đầu tiên của dự án, hãy thêm dòng mã sau đây. Ngoài ra, hãy thêm vào phương thức OnApplicationPause() nếu bạn muốn gửi dữ liệu phiên khi người dùng tiếp tục sử dụng ứng dụng từ chế độ nền.
C#
using UnityEngine;
using System.Collections;

public class TenjinExampleScript : MonoBehaviour {

  void Start() {
    TenjinConnect();
  }

  void OnApplicationPause(bool pauseStatus) {
    if (!pauseStatus) {
      TenjinConnect();
    }
  }

  public void TenjinConnect() {
    BaseTenjin instance = Tenjin.getInstance("");

    // Sends Install/open event to Tenjin
    instance.Connect();
  }
}

LƯU Ý: Vui lòng đảm bảo triển khai đoạn mã này trong mọi phương thức Start() và OnApplicationPause(), không chỉ khi ứng dụng được mở lần đầu tiên.

App Store #

Chúng tôi hỗ trợ ba tùy chọn cửa hàng ứng dụng,

  1. Google Play
  2. amazon
  3. khác

Theo mặc định, không xác định là App Store mặc định. Nếu bạn đang phát hành ứng dụng trên một App Store cụ thể, hãy cập nhật giá trị App Store thành giá trị tương ứng. Giá trị App Store khác được sử dụng cho Huawei AppGallery và các App Store khác:

  1. AndroidManifest.xml:
XML
<meta-data
    android:name="TENJIN_APP_STORE"
    android:value="{{SET_APP_STORE_TYPE_VALUE}}" />
  1. SetAppStoreType():
C#
BaseTenjin instance = Tenjin.getInstance("");

instance.SetAppStoreType(AppStoreType.{{SET_APP_STORE_TYPE_VALUE}});

ATTrackingManager (iOS) #

  • Bắt đầu từ phiên bản iOS 14, bạn có thể chọn hiển thị thông báo yêu cầu quyền ban đầu của ATTrackingManager cùng với tùy chọn cho phép hoặc từ chối đối với người dùng.
  • Nếu thiết bị không chấp nhận quyền theo dõi, giá trị IDFA sẽ bằng 0. Nếu thiết bị chấp nhận quyền theo dõi, phương thức Connect() sẽ gửi giá trị IDFA đến máy chủ của chúng tôi.
  • Bạn cũng vẫn có thể gọi hàm connect() của Tenjin mà không cần sử dụng ATTrackingManager. Bạn có thể chọn không triển khai ATT nếu không có ý định truy cập hoặc truyền IDFA của bất kỳ người dùng nào sang Tenjin.
C#
using UnityEngine;
using System.Collections;
using UnityEngine.iOS;

public class TenjinExampleScript : MonoBehaviour {

    void Start() {
        TenjinConnect();
    }

    void OnApplicationPause(bool pauseStatus) {
        if (!pauseStatus) {
            TenjinConnect();
        }
    }

    public void TenjinConnect() {
        BaseTenjin instance = Tenjin.getInstance("SDK_KEY");

        #if UNITY_IOS
        if (new Version(Device.systemVersion).CompareTo(new Version("14.0")) >= 0) {
            // Tenjin wrapper for requestTrackingAuthorization
            instance.RequestTrackingAuthorizationWithCompletionHandler((status) => {
                Debug.Log("===> App Tracking Transparency Authorization Status: " + status);
                // Sends Install/open event to Tenjin
                instance.Connect();
            });
        }
        else {
            instance.Connect();
        }
        #elif UNITY_ANDROID
        // Sends Install/open event to Tenjin
        instance.Connect();
        #endif
    }
}

Hiển thị thông báo yêu cầu quyền ATT #

Để tuân thủ các hướng dẫn về ATT của Apple, bạn phải cung cấp phần mô tả cho thông báo yêu cầu quyền ATT, sau đó triển khai tính năng yêu cầu quyền này trong ứng dụng của mình.

> Lưu ý: Bạn phải triển khai yêu cầu cấp quyền trước khi hiển thị quảng cáo trong trò chơi của mình.

Cấu hình mô tả theo dõi người dùng #

Apple yêu cầu phải có phần mô tả cho thông báo yêu cầu quyền ATT. Bạn cần thiết lập mô tả này bằng khóa NSUserTrackingUsageDescription trong tệp Info.plist của dự án Xcode. Bạn phải cung cấp một thông báo giải thích cho người dùng lý do tại sao bạn yêu cầu quyền sử dụng dữ liệu theo dõi thiết bị:

  • Trong trình duyệt dự án Xcode của bạn, hãy mở tệp Info.plist.
  • Nhấp vào nút Thêm (+) bên cạnh bất kỳ khóa thuộc tính nào trong trình chỉnh sửa danh sách thuộc tính để tạo một khóa thuộc tính mới.
  • Nhập tên khóa NSUserTrackingUsageDescription.
  • Chọn kiểu giá trị chuỗi.
  • Nhập thông báo về tính minh bạch trong việc theo dõi ứng dụng vào trường giá trị. Một số ví dụ bao gồm:
    • “Chúng tôi sẽ sử dụng dữ liệu của bạn để mang đến trải nghiệm quảng cáo tốt hơn và được cá nhân hóa.”
    • “Chúng tôi cố gắng hiển thị các quảng cáo về ứng dụng và sản phẩm mà bạn có thể quan tâm nhất, dựa trên các ứng dụng bạn đang sử dụng, thiết bị bạn đang dùng và quốc gia bạn đang sinh sống.”
    • “Chúng tôi cố gắng hiển thị các quảng cáo về ứng dụng và sản phẩm mà bạn có thể quan tâm nhất dựa trên các ứng dụng bạn đang sử dụng.”

> Lưu ý: Apple cung cấp các hướng dẫn cụ thể của App Store quy định về cách sử dụng và thông báo được chấp nhận đối với tất cả các tính năng liên quan đến quyền riêng tư dành cho người dùng cuối. Tenjin không cung cấp tư vấn pháp lý. Do đó, thông tin trên trang này không thể thay thế cho việc tìm kiếm tư vấn pháp lý riêng của bạn để xác định các yêu cầu pháp lý đối với doanh nghiệp và quy trình của bạn, cũng như cách thức tuân thủ các yêu cầu đó.

SKAdNetwork và các giá trị chuyển đổi #

Là một phần của SKAdNetwork, chúng tôi đã tạo phương thức wrapper cho updatePostbackConversionValue(_:). Phương thức của chúng tôi sẽ đăng ký các phương thức tương ứng của SKAdNetwork và cũng gửi các giá trị chuyển đổi đến máy chủ của chúng tôi.

updatePostbackConversionValue(_:) Giá trị 6 bit phải tương ứng với sự kiện trong ứng dụng và không được nhập dưới dạng biểu diễn nhị phân mà phải là số nguyên trong khoảng từ 0 đến 63. Máy chủ của chúng tôi sẽ từ chối bất kỳ giá trị không hợp lệ nào.

Kể từ phiên bản iOS 16.1, hỗ trợ SKAdNetwork 4.0, giờ đây bạn có thể gửi coarseValue (chuỗi ký tự, với các giá trị có thể là “low”, “medium” hoặc “high”) và lockWindow (Boolean) làm tham số trong phương thức postback cập nhật:

updatePostbackConversionValue(conversionValue: Integer, coarseValue: String)

updatePostbackConversionValue(conversionValue: Integer, coarseValue: String, lockWindow: Bool)

  • Đối với phiên bản iOS 16.1 trở lên hỗ trợ SKAdNetwork 4.0, bạn có thể gọi phương thức này bao nhiêu lần tùy ý và có thể đặt giá trị Chuyển đổi thấp hơn hoặc cao hơn giá trị trước đó.
  • Đối với các phiên bản iOS thấp hơn 16.1 hỗ trợ các phiên bản SKAdNetwork thấp hơn 4.0, bạn có thể gọi phương thức này và SDK của chúng tôi sẽ tự động phát hiện phiên bản iOS và chỉ cập nhật conversionValue mà thôi.
C#
using UnityEngine;
using System.Collections;

public class TenjinExampleScript : MonoBehaviour {

    void Start() {
        TenjinConnect();
    }

    void OnApplicationPause(bool pauseStatus) {
        if (!pauseStatus) {
            TenjinConnect();
        }
    }

    public void TenjinConnect() {
        BaseTenjin instance = Tenjin.getInstance("SDK_KEY");

        #if UNITY_IOS
        // Sends Install/open event to Tenjin
        instance.Connect();

        // Sets SKAdNetwork Conversion Value
        // You will need to use a value between 0-63
        instance.updatePostbackConversionValue(<Integer between 0 and 63>);

        // For iOS 16.1+ (SKAN 4.0)
        instance.updatePostbackConversionValue(<Integer between 0 and 63>, "medium");
        instance.updatePostbackConversionValue(<Integer between 0 and 63>, "medium", true);
        #elif UNITY_ANDROID
        // Sends Install/open event to Tenjin
        instance.Connect();
        #endif
    }
}

SKAdNetwork và iOS: Dữ liệu phản hồi từ nhà quảng cáo dành cho người dùng từ 15 tuổi trở lên #

Để chỉ định Tenjin làm điểm đến cho các postback của mạng quảng cáo SK Ad Network, hãy thực hiện như sau:

  1. Chọn Info.plist trong trình duyệt Dự án (Project navigator) trong Xcode.
  2. Nhấp vào nút Thêm (+) bên cạnh một khóa trong trình chỉnh sửa danh sách thuộc tính và nhấn phím Return.
  3. Nhập tên khóa NSAdvertisingAttributionReportEndpoint.
  4. Chọn “String” từ menu thả xuống trong cột “Type”.
  5. Nhập https://tenjin-skan.com

Các bước này được điều chỉnh dựa trên hướng dẫn của Apple tại https://developer.apple.com/documentation/storekit/skadnetwork/configuring_an_advertised_app.

GDPR #

Trong khuôn khổ việc tuân thủ GDPR, với SDK của Tenjin, bạn có thể cho phép hoặc từ chối thu thập dữ liệu từ các thiết bị/người dùng, hoặc chọn các tham số cụ thể liên quan đến thiết bị để cho phép hoặc từ chối thu thập. OptOut() sẽ không gửi bất kỳ yêu cầu API nào đến Tenjin, và chúng tôi sẽ không xử lý bất kỳ sự kiện nào.

Để đăng ký/hủy đăng ký:

C#
void Start () {

  BaseTenjin instance = Tenjin.getInstance("SDK_KEY");

  boolean userOptIn = CheckOptInValue();

  if (userOptIn) {
    instance.OptIn();
  }
  else {
    instance.OptOut();
  }

  instance.Connect();
}

boolean CheckOptInValue()
{
  // check opt-in value
  // return true; // if user opted-in
  return false;
}
  • Để chọn tham gia hoặc từ chối các tham số cụ thể liên quan đến thiết bị, bạn có thể sử dụng hàm OptInParams() hoặc OptOutParams().
  • OptInParams() sẽ chỉ gửi các tham số liên quan đến thiết bị đã được chỉ định. OptOutParams() sẽ gửi tất cả các tham số liên quan đến thiết bị, trừ những tham số được chỉ định.
  • Xin lưu ý rằng chúng tôi yêu cầu các tham số sau đây để theo dõi thiết bị một cách chính xác trong hệ thống của Tenjin. Nếu thiếu một trong các tham số bắt buộc này, sự kiện sẽ không được xử lý hoặc ghi lại.
  • Đối với Android,
    • advertising_id
  • Dành cho iOS
    • developer_device_id
  • Nếu bạn đang nhắm mục tiêu các mạng quảng cáo dựa trên IMEI và/hoặc OAID cho Android, hãy thêm:
    • imei
    • oaid
  • Nếu bạn có ý định sử dụng Google AdWords, bạn cũng cần thêm:
    • platform
    • os_version
    • app_version
    • locale
    • device_model
    • build_id
    • advertising_id
    • developer_device_id (dành cho iOS)

Nếu bạn chỉ muốn lấy các tham số cụ thể liên quan đến thiết bị, hãy sử dụng OptInParams(). Trong ví dụ dưới đây, chúng ta sẽ chỉ lấy các tham số liên quan đến thiết bị sau: ip_address, advertising_id, developer_device_id, limit_ad_tracking, và referrer:

C#
BaseTenjin instance = Tenjin.getInstance("SDK_KEY");

List<string> optInParams = new List<string> {"ip_address", "advertising_id", "developer_device_id", "limit_ad_tracking", "referrer", "iad"};
instance.OptInParams(optInParams);

instance.Connect();

Nếu bạn muốn gửi TẤT CẢ các tham số ngoại trừ các tham số cụ thể liên quan đến thiết bị, hãy sử dụng OptOutParams(). Trong ví dụ dưới đây, chúng tôi sẽ gửi TẤT CẢ các tham số liên quan đến thiết bị ngoại trừ: locale, timezone và build_id.

C#
BaseTenjin instance = Tenjin.getInstance("SDK_KEY");

List<string> optOutParams = new List<string> {"locale", "timezone", "build_id"};
instance.OptOutParams(optOutParams);

instance.Connect();

Chọn tham gia/từ chối thông qua CMP #

Bạn có thể tự động chọn tham gia hoặc từ chối tham gia bằng cách sử dụng các quyền đồng ý CMP (mục đích 1) đã được lưu trữ sẵn trên thiết bị của người dùng. Phương thức này trả về một giá trị boolean để thông báo cho bạn biết người dùng đã chọn tham gia hay từ chối tham gia.

OptInOutUsingCMP()

C#
BaseTenjin instance = Tenjin.getInstance("");
optInOut = instance.OptInOutUsingCMP();

Các thông số liên quan đến thiết bị #

Tham sốMô tảNền tảng
địa chỉ IPĐịa chỉ IPTất cả
id_quảng_cáoID quảng cáo của thiết bịTất cả
id_thiết_bị_nhà_phát_triểnMã số nhà cung cấpiOS
oaidMã nhận dạng quảng cáo mởAndroid
IMEISố IMEI của thiết bịAndroid
giới hạn theo dõi quảng cáoĐã bật tính năng giới hạn theo dõi quảng cáoTất cả
nền tảngnền tảngTất cả
nguồn giới thiệuNguồn giới thiệu cài đặt từ Google PlayAndroid
os_versionphiên bản hệ điều hànhTất cả
thiết bịtên thiết bịTất cả
nhà sản xuất thiết bịnhà sản xuất thiết bịAndroid
mẫu thiết bịmẫu thiết bịTất cả
thương hiệu_thiết_bịthương hiệu thiết bịAndroid
thiết bị_sản phẩmsản phẩm thiết bịAndroid
tên_mẫu_thiết_bịthiết bị máy móciOS
device_cpuTên CPU của thiết bịiOS
nhà mạngnhà mạng di độngAndroid
loại kết nốimạng di động hoặc Wi-FiAndroid
chiều rộng màn hìnhchiều rộng màn hình thiết bịAndroid
chiều cao màn hìnhchiều cao màn hình thiết bịAndroid
os_version_releasephiên bản hệ điều hànhTất cả
build_idID bản dựngTất cả
địa phươngcài đặt ngôn ngữ của thiết bịTất cả
quốc giavùng ngôn ngữ, quốc giaTất cả
múi giờmúi giờTất cả


Các sự kiện mua sắm #

Xác thực IAP iOS #

Quá trình xác thực biên lai iOS yêu cầu mã giao dịch (transactionId) và biên lai. Chữ ký sẽ được đặt thành null. Đối với biên lai, hãy đảm bảo gửi Payload của biên lai (biên lai ASN.1 được mã hóa base64) từ Unity.

QUAN TRỌNG: Nếu bạn có gói đăng ký IAP, bạn sẽ cần thêm khóa công khai của ứng dụng vào bảng điều khiển Tenjin. Bạn có thể lấy Mật khẩu chia sẻ dành riêng cho ứng dụng iOS từ Bảng điều khiển iTunes Connect > Chọn ứng dụng của bạn > Thông tin ứng dụng > Mật khẩu chung dành riêng cho ứng dụng.

Xác thực IAP Android #

Cửa hàng ứng dụng Google Play

Quá trình xác thực hóa đơn trên Google Play yêu cầu phải có hóa đơn và chữ ký (transactionId được đặt thành null).

QUAN TRỌNG: Bạn cần thêm khóa công khai của ứng dụng vào bảng điều khiển Tenjin (trong trang ‘chỉnh sửa’ của ứng dụng). Bạn có thể lấy khóa công khai RSA được mã hóa Base64 từ Google Play Developer Console > Chọn ứng dụng của bạn > Kiếm tiền > Cài đặt kiếm tiền > Thanh toán Google Play > Cấp phép: Khóa công khai RSA được mã hóa Base64. Xin lưu ý rằng đối với Android, hiện tại chúng tôi chỉ hỗ trợ các giao dịch IAP từ Google Play.

(LƯU Ý) Đối với Google Play, vui lòng đảm bảo đã ‘xác nhận’ sự kiện mua hàng trước khi gửi dữ liệu này đến Tenjin. Để biết thêm chi tiết, vui lòng đọc tại đây

Ứng dụng Amazon trên App Store

Quá trình xác thực biên lai trên AppStore của Amazon yêu cầu các tham số receiptId và userId.

QUAN TRỌNG: Bạn cần thêm Khóa chia sẻ của ứng dụng Amazon vào bảng điều khiển Tenjin. Khóa chia sẻ này có thể được tìm thấy trong phần "Shared Key" (Khóa chia sẻ) của tài khoản nhà phát triển liên kết với tài khoản Amazon Appstore

Ví dụ về iOS và Android IAP #

Trong ví dụ dưới đây, chúng ta đang sử dụng thư viện MiniJSON — một thư viện được sử dụng rộng rãi — để giải mã JSON.

Nếu bạn đang sử dụng Unity IAP phiên bản 5 trở lên:

Đối với các sản phẩm tiêu hao, biên lai chỉ có sẵn trong PendingOrder. Sau khi được xác nhận (ConfirmedOrder), biên lai sẽ trống. Luôn xử lý các giao dịch mua và gửi đến Tenjin trong trạng thái OnPurchasePending đối với các sản phẩm tiêu hao.

C#
public static void OnPurchasePending(PendingOrder pendingOrder) {
    ProcessOrder(pendingOrder);
    // Confirm the purchase after processing
    UnityIAPServices.DefaultPurchase().ConfirmPurchase(pendingOrder);
}

public static void ProcessOrder(Order order) {
    // Get the first item from the cart
    var item = order.CartOrdered.Items().FirstOrDefault();
    if (item == null) return;

    var product = item.Product;
    var price = product.metadata.localizedPrice;
    double lPrice = decimal.ToDouble(price);
    var currencyCode = product.metadata.isoCurrencyCode;
    var productId = product.definition.id;
    var info = order.Info;

#if UNITY_ANDROID

    // Parse the unified receipt JSON
    var wrapper = Json.Deserialize(info.Receipt) as Dictionary<string, object>;  // https://gist.github.com/darktable/1411710
    if (wrapper == null) return;

    var store   = (string)wrapper["Store"];
    var payload = (string)wrapper["Payload"];

    if (store.Equals("GooglePlay")) {
        var googleDetails = Json.Deserialize(payload) as Dictionary<string, object>;
        var googleJson    = (string)googleDetails["json"];
        var googleSig     = (string)googleDetails["signature"];

        CompletedAndroidPurchase(productId, currencyCode, 1, lPrice, googleJson, googleSig);
    }

    if (store.Equals("AmazonAppStore")) {
        var amazonDetails   = Json.Deserialize(payload) as Dictionary<string, object>;
        var amazonReceiptId = (string)amazonDetails["receiptId"];
        var amazonUserId    = (string)amazonDetails["userId"];

        CompletedAmazonPurchase(productId, currencyCode, 1, lPrice, amazonReceiptId, amazonUserId);
    }

#elif UNITY_IOS

    // Try SK2 first (Unity IAP 5.1+ on iOS 15+), fall back to SK1
    var receipt = info.Apple?.jwsRepresentation;
    if (string.IsNullOrEmpty(receipt)) {
        receipt = info.Apple?.AppReceipt;
    }

    if (string.IsNullOrEmpty(receipt)) {
        Debug.LogError("No receipt available");
        return;
    }

    var transactionId = info.TransactionID;
    CompletedIosPurchase(productId, currencyCode, 1, lPrice, transactionId, receipt);

#endif
}

private static void CompletedAndroidPurchase(string ProductId, string CurrencyCode, int Quantity,
                                            double UnitPrice, string Receipt, string Signature)
{
    BaseTenjin instance = Tenjin.getInstance("SDK_KEY");
    instance.Transaction(ProductId, CurrencyCode, Quantity, UnitPrice, null, Receipt, Signature);
}

private static void CompletedIosPurchase(string ProductId, string CurrencyCode, int Quantity,
                                        double UnitPrice, string TransactionId, string Receipt)
{
    BaseTenjin instance = Tenjin.getInstance("SDK_KEY");
    instance.Transaction(ProductId, CurrencyCode, Quantity, UnitPrice, TransactionId, Receipt, null);
}

private static void CompletedAmazonPurchase(string ProductId, string CurrencyCode, int Quantity,
                                            double UnitPrice, string ReceiptId, string UserId)
{
    BaseTenjin instance = Tenjin.getInstance("SDK_KEY");
    instance.TransactionAmazon(ProductId, CurrencyCode, Quantity, UnitPrice, ReceiptId, UserId);
}

Nếu bạn đang sử dụng Unity IAP phiên bản 4 (hoặc các phiên bản trước đó):

C#
public static void OnProcessPurchase(PurchaseEventArgs purchaseEventArgs) {
    var price = purchaseEventArgs.purchasedProduct.metadata.localizedPrice;
    double lPrice = decimal.ToDouble(price);
    var currencyCode = purchaseEventArgs.purchasedProduct.metadata.isoCurrencyCode;

    var wrapper = Json.Deserialize(purchaseEventArgs.purchasedProduct.receipt) as Dictionary<string, object>;
    // https://gist.github.com/darktable/1411710
    if (null == wrapper) {
        return;
    }

    var store     = (string)wrapper["Store"];    // GooglePlay, AmazonAppStore, AppleAppStore, etc.
    var payload   = (string)wrapper["Payload"];  // For Apple: base64 encoded ASN.1 receipt. For Android: raw JSON receipt.
    var productId = purchaseEventArgs.purchasedProduct.definition.id;

    #if UNITY_ANDROID
    if (store.Equals("GooglePlay")) {
        var googleDetails = Json.Deserialize(payload) as Dictionary<string, object>;
        var googleJson    = (string)googleDetails["json"];
        var googleSig     = (string)googleDetails["signature"];
        CompletedAndroidPurchase(productId, currencyCode, 1, lPrice, googleJson, googleSig);
    }
    if (store.Equals("AmazonApps")) {
        var amazonDetails   = Json.Deserialize(payload) as Dictionary<string, object>;
        var amazonReceiptId = (string)amazonDetails["receiptId"];
        var amazonUserId    = (string)amazonDetails["userId"];
        CompletedAmazonPurchase(productId, currencyCode, 1, lPrice, amazonReceiptId, amazonUserId);
    }
    #elif UNITY_IOS
    var transactionId = purchaseEventArgs.purchasedProduct.transactionID;
    CompletedIosPurchase(productId, currencyCode, 1, lPrice, transactionId, payload);
    #endif
}

private static void CompletedAndroidPurchase(string ProductId, string CurrencyCode, int Quantity, double UnitPrice, string Receipt, string Signature) {
    BaseTenjin instance = Tenjin.getInstance("SDK_KEY");
    instance.Transaction(ProductId, CurrencyCode, Quantity, UnitPrice, null, Receipt, Signature);
}

private static void CompletedIosPurchase(string ProductId, string CurrencyCode, int Quantity, double UnitPrice, string TransactionId, string Receipt) {
    BaseTenjin instance = Tenjin.getInstance("SDK_KEY");
    instance.Transaction(ProductId, CurrencyCode, Quantity, UnitPrice, TransactionId, Receipt, null);
}

private static void CompletedAmazonPurchase(string ProductId, string CurrencyCode, int Quantity, double UnitPrice, string ReceiptId, string UserId) {
    BaseTenjin instance = Tenjin.getInstance("SDK_KEY");
    instance.TransactionAmazon(ProductId, CurrencyCode, Quantity, UnitPrice, ReceiptId, UserId);
}

(Cài đặt mức hoa hồng App Store linh hoạt) Bạn có thể lựa chọn giữa các mức hoa hồng doanh thu của App Store là 0%, 15% và 30% thông qua tính năng cài đặt mới của chúng tôi. Các bước thực hiện như sau –

  • Chuyển đến CÀI ĐẶT –> Ứng dụng
  • Nhấp vào ứng dụng mà bạn muốn thay đổi cài đặt
  • Trong phần ‘Phí hoa hồng App Store’, hãy nhấp vào ‘Chỉnh sửa’
  • Hãy chọn 30%, 15% hoặc 0% làm mức hoa hồng từ cửa hàng ứng dụng mà bạn mong muốn.
  • Chọn ngày bắt đầu và ngày kết thúc (Hoặc bạn có thể để trống ô ngày kết thúc nếu không muốn chỉ định ngày kết thúc)
  • Nhấp vào “Lưu” (lưu ý: mức hoa hồng chỉ có thể áp dụng cho các ngày trong tương lai, không áp dụng cho các ngày đã qua. Do đó, vui lòng đặt ngày bắt đầu từ ngày bạn thực hiện thay đổi trở đi)

Gói đăng ký IAP #

  • Bạn có trách nhiệm gửi một giao dịch đăng ký một lần trong mỗi khoảng thời gian đăng ký (tức là, ví dụ: đối với gói đăng ký hàng tháng, bạn sẽ cần gửi cho chúng tôi 1 giao dịch mỗi tháng). Trong dòng thời gian ví dụ dưới đây, sự kiện giao dịch chỉ nên được gửi tại các sự kiện “Lần thanh toán đầu tiên” và “Gia hạn”. Trong thời gian dùng thử, vui lòng không gửi sự kiện giao dịch cho Tenjin.

Sự kiện tùy chỉnh #

QUAN TRỌNG: Hạn chế độ dài tên sự kiện tùy chỉnh dưới 80 ký tự. Không được vượt quá 500 tên sự kiện tùy chỉnh khác nhau.

  • Thêm thư mục Assets vào dự án Unity của bạn
  • Trong phương thức xử lý sự kiện tùy chỉnh của dự án, hãy viết đoạn mã sau cho một sự kiện có tên: Tenjin.getInstance("").SendEvent("name") và đoạn mã sau đây cho sự kiện có tên kèm theo giá trị số nguyên: Tenjin.getInstance("").SendEvent("nameWithValue","value")
  • Hãy đảm bảo rằng giá trị được truyền vào là một giá trị số nguyên (ví dụ: “2000”, không phải “0.02”). Nếu value không phải là một giá trị số nguyên, tham số value sẽ bị bỏ qua.

Dưới đây là một ví dụ về đoạn mã:

C#
void MethodWithCustomEvent(){
    //event with name
    BaseTenjin instance = Tenjin.getInstance ("SDK_KEY");
    instance.SendEvent("name");

    //event with name and integer value
    instance.SendEvent("nameWithValue", "value");
}

.SendEvent("name") được dùng cho các sự kiện là các mốc cố định hoặc các cột mốc quan trọng. Điều này bao gồm các mục như tutorial_complete, registration, hoặc level_1.

.SendEvent("name", "value") được dùng cho các sự kiện mà bạn muốn thực hiện phép tính trên một thuộc tính của sự kiện đó. Ví dụ: ("coins_purchased", "100") sẽ cho phép bạn phân tích tổng hoặc trung bình số xu được mua trong sự kiện đó.

Tích hợp giữa các máy chủ #

Tenjin cung cấp tích hợp giữa các máy chủ. Tính năng này cho phép bạn gửi các sự kiện cài đặt và sau khi cài đặt trực tiếp từ máy chủ của bạn đến máy chủ của Tenjin mà không cần tích hợp SDK.

Tham số “Subversion” của ứng dụng dành cho thử nghiệm A/B #

Nếu bạn đang thực hiện các thử nghiệm A/B và muốn báo cáo sự khác biệt, chúng tôi có thể thêm một giá trị số vào phiên bản ứng dụng của bạn bằng cách sử dụng phương thức AppendAppSubversion(). Ví dụ: nếu phiên bản ứng dụng của bạn là 1.0.1 và bạn đặt AppendAppSubversion(8888), ứng dụng sẽ hiển thị phiên bản là 1.0.1.8888.

Dữ liệu này sẽ xuất hiện trong DataVault, nơi bạn có thể tạo báo cáo bằng cách sử dụng các giá trị phiên bản phụ của ứng dụng.

C#
BaseTenjin instance = Tenjin.getInstance("");
instance.AppendAppSubversion(8888);
instance.Connect();

Chiến dịch LiveOps #

Tenjin hỗ trợ việc truy xuất thông tin gán nguồn (Attribution) của người dùng, chẳng hạn như mạng quảng cáo (Ad Network) và chiến dịch, từ SDK. Điều này sẽ cho phép các nhà phát triển thu thập và phân tích dữ liệu gán nguồn ở cấp độ người dùng theo thời gian thực. Dưới đây là các trường hợp sử dụng có thể áp dụng với Tenjin LiveOps Campaigns:

  • Nếu bạn có công cụ phân tích dữ liệu riêng, tính năng S2S callback sẽ cho phép bạn liên kết dữ liệu Attribution với dữ liệu trong trò chơi ở cấp độ từng thiết bị.
  • Hiển thị nội dung ứng dụng khác nhau tùy thuộc vào nguồn truy cập của người dùng. Ví dụ: nếu người dùng A được xác định là đến từ kết quả tìm kiếm tự nhiên, còn người dùng B được xác định là đến từ Facebook và người dùng B có khả năng tương tác nhiều hơn với ứng dụng của bạn, thì bạn nên hiển thị một ưu đãi đặc biệt trong trò chơi sau khi người dùng cài đặt ứng dụng. Nếu bạn muốn thảo luận về các trường hợp sử dụng cụ thể hơn, vui lòng gửi email đến support@tenjin.com.

Thông tin chi tiết về cách sử dụng LiveOps có thể được tìm thấy tại đây.

ID người dùng của khách hàng #

Bạn có thể thiết lập và lấy ID người dùng của khách hàng để gửi dưới dạng tham số trong các sự kiện.

.SetCustomerUserId("user_id")

.GetCustomerUserId()

C#
BaseTenjin instance = Tenjin.getInstance("");
instance.SetCustomerUserId("user_id");
string userId = instance.GetCustomerUserId();

ID cài đặt Analytics #

Bạn có thể lấy ID phân tích, được tạo ngẫu nhiên và lưu trữ trong bộ nhớ cục bộ của thiết bị. GetAnalyticsInstallationId()

C#
BaseTenjin instance = Tenjin.getInstance("");
analyticsId = instance.GetAnalyticsInstallationId;

Sự kiện thử lại/bộ nhớ đệm #

Bạn có thể bật/tắt tính năng thử lại và lưu vào bộ nhớ đệm cho tất cả các sự kiện khi yêu cầu không thành công hoặc người dùng không có kết nối Internet. Các sự kiện này sẽ được gửi đi sau khi một sự kiện mới được thêm vào hàng đợi và người dùng đã khôi phục kết nối.

.SetCacheEventSetting(true)

C#
BaseTenjin instance = Tenjin.getInstance("");
instance.SetCacheEventSetting(true);

Các tham số DMA của Google #

Nếu bạn đã tích hợp CMP, các tham số Google DMA sẽ được SDK Tenjin thu thập tự động. Bạn không cần thực hiện bất kỳ thao tác nào trong SDK Tenjin nếu đã tích hợp CMP. Nếu bạn muốn ghi đè lên CMP hiện có hoặc đơn giản là muốn xây dựng cơ chế xin sự đồng ý của riêng mình, bạn có thể sử dụng các phương án sau:

SetGoogleDMAParameters(bool, bool)

C#
BaseTenjin instance = Tenjin.getInstance("");
instance.SetGoogleDMAParameters(adPersonalization, adUserData);

Để quản lý một cách rõ ràng việc thu thập các thông số Google DMA, bạn có thể linh hoạt chọn tham gia hoặc từ chối tham gia bất cứ lúc nào. Mặc dù cài đặt mặc định là tham gia, bạn có thể dễ dàng điều chỉnh các tùy chọn của mình bằng cách sử dụng các phương thức OptInGoogleDMA hoặc OptOutGoogleDMA, đảm bảo quyền kiểm soát hoàn toàn đối với các cài đặt bảo mật dữ liệu của mình:

C#
instance.OptInGoogleDMA(); 
instance.OptOutGoogleDMA();

Hồ sơ người dùng – Các chỉ số của LiveOps #

Tenjin SDK tự động theo dõi và tổng hợp các chỉ số về phiên người dùng (Session) và doanh thu, có thể được sử dụng cho các chiến dịch LiveOps, phân khúc người dùng và phân tích dữ liệu. Tính năng Hồ sơ người dùng (User Profile) cho phép truy cập theo thời gian thực vào các chỉ số này đối với từng người dùng cụ thể.

Các chỉ số được theo dõi #

SDK tự động theo dõi các chỉ số sau đây cho từng người dùng:

Hệ métMô tảLoại
session_countTổng số phiênSố nguyên
total_session_timeThời gian phiên tích lũy trong mili giâySố
average_session_lengthThời lượng phiên trung bình trong mili giâySố
last_session_lengthThời lượng phiên làm việc gần nhất đã hoàn tất là mili giâySố
iap_transaction_countTổng số giao dịch IAPSố nguyên
total_ilrd_revenue_usdTổng doanh thu quảng cáo của ILRD tính bằng USDSố
first_session_dateDấu thời gian theo tiêu chuẩn ISO 8601 của phiên đầu tiênDây
last_session_dateDấu thời gian theo tiêu chuẩn ISO 8601 của phiên làm việc gần đây nhất đã hoàn tấtDây
current_session_lengthThời lượng phiên hiện tại là mili giâySố
iap_revenue_by_currencyPhân tích doanh thu theo mã tiền tệChuỗi JSON
purchased_product_idsMảng các mã sản phẩm đã muaChuỗi JSON
ilrd_revenue_by_networkDoanh thu của ILRD theo mạng quảng cáoChuỗi JSON

Lưu ý: Các trường có điều kiện (ngày tháng, phiên hiện tại, bản đồ doanh thu, mảng sản phẩm) chỉ được đưa vào từ điển nếu có dữ liệu.

Các phương pháp hiện có #

Lấy từ điển hồ sơ người dùng #

Trả về một từ điển chứa tất cả các chỉ số được theo dõi của người dùng hiện tại. Tất cả các giá trị đều được trả về dưới dạng chuỗi ký tự (các số, mảng JSON và đối tượng JSON sẽ được chuyển đổi thành chuỗi ký tự).

C#
BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");
Dictionary<string, string> profile = instance.GetUserProfileDictionary();

if (profile != null && profile.Count > 0)
{
    Debug.Log("Session Count: " + profile["session_count"]);
    Debug.Log("Total Session Time (ms): " + profile["total_session_time"]);
    Debug.Log("Average Session Length (ms): " + profile["average_session_length"]);
    Debug.Log("Last Session Length (ms): " + profile["last_session_length"]);
    Debug.Log("IAP Transaction Count: " + profile["iap_transaction_count"]);
    Debug.Log("Total ILRD Revenue USD: " + profile["total_ilrd_revenue_usd"]);

    // Convert milliseconds to seconds if needed
    long totalTimeMs = long.Parse(profile["total_session_time"]);
    Debug.Log($"Total Session Time: {totalTimeMs / 1000.0:F1} seconds");

    // Revenue by currency is a JSON string (conditional)
    if (profile.ContainsKey("iap_revenue_by_currency"))
    {
        Debug.Log("IAP Revenue by Currency: " + profile["iap_revenue_by_currency"]);
        // Example: {"USD":99.99,"EUR":49.99}
    }

    // Product IDs is a JSON array string (conditional)
    if (profile.ContainsKey("purchased_product_ids"))
    {
        Debug.Log("Purchased Products: " + profile["purchased_product_ids"]);
        // Example: ["com.app.coins100","com.app.coins500"]
    }
}
else
{
    Debug.Log("User profile not available yet");
}

Đặt lại hồ sơ người dùng #

Xóa tất cả các chỉ số đang được theo dõi của người dùng hiện tại. Tính năng này hữu ích trong quá trình thử nghiệm hoặc khi người dùng đăng xuất.

C#
BaseTenjin instance = Tenjin.getInstance("<SDK_KEY>");
instance.ResetUserProfile();
Debug.Log("User profile has been reset");

Lưu ý dành riêng cho từng nền tảng #

Tính sẵn có của dữ liệu:

Dữ liệu hồ sơ người dùng sẽ có sẵn sau khi phiên đầu tiên được theo dõi. Phương thức GetUserProfileDictionary() trả về dữ liệu thời gian thực từ bộ nhớ đệm trong bộ nhớ của SDK.

Đơn vị thời gian:

  1. Tất cả các giá trị thời gian hiện được tính bằng mili giây trên cả iOS và Android để đảm bảo tính nhất quán
  2. Chuyển đổi sang giây nếu cần: milliseconds / 1000.0

Các kiểu dữ liệu phức tạp:

  1. Các bản đồ doanh thu (iap_revenue_by_currency, ilrd_revenue_by_network) được trả về dưới dạng chuỗi JSON: {"USD":99.99,"EUR":49.99}
  2. Các mảng ID sản phẩm (purchased_product_ids) được trả về dưới dạng chuỗi JSON: ["product1","product2"]

Tích hợp doanh thu quảng cáo theo mức độ hiển thị #

Tenjin hỗ trợ khả năng tích hợp với tính năng Doanh thu quảng cáo theo số lần hiển thị (ILRD) từ,

  • AppLovin MAX
  • Unity LevelPlay
  • HyperBid
  • AdMob
  • TopOn
  • CAS
  • TradPlus
  • CloudX

Tính năng này cho phép bạn nhận các sự kiện liên quan đến doanh thu quảng cáo của bạn, vốn bị ảnh hưởng bởi mỗi quảng cáo được hiển thị cho người dùng. Bạn có thể truy cập hướng dẫn tích hợp tại đây.

Kiểm thử #

Bạn có thể kiểm tra xem quá trình tích hợp có hoạt động chính xác hay không bằng Công cụ Kiểm tra Dữ liệu Thiết bị Trực tiếp của chúng tôi. Thêm advertising_id hoặc IDFA/GAID của bạn vào danh sách các thiết bị thử nghiệm. Bạn có thể tìm thấy thông tin này tại mục Hỗ trợ -> Thiết bị thử nghiệm. Truy cập trang Công cụ Sự kiện Trực tiếp và gửi các sự kiện thử nghiệm từ ứng dụng của bạn. Bạn sẽ thấy các sự kiện trực tiếp được gửi đến:

Cảm xúc của bạn là gì