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

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

Tích hợp bằng cách sử dụng các mô hình ngôn ngữ lớn (LLM) (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/ios/llm-guide.md

Tóm tắt #

Bộ công cụ phát triển phần mềm (SDK) Tenjin iOS cho phép người dùng theo dõi các sự kiện và lượt cài đặt trong các ứng dụng iOS của họ. Để 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 phiên bản chi tiết.
Để xem hướng dẫn dành riêng cho Unity, vui lòng truy cập https://github.com/tenjin/tenjin-unity-sdk.
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

Ghi chú: #

Yêu cầu Xcode 13, nếu bạn đang sử dụng SDK iOS phiên bản 1.12.17 trở lên.
Đối với AppTrackingTransparency, hãy đảm bảo cập nhật tệp .plist của dự án và thêm Mô tả về quyền riêng tư - Mô tả việc theo dõi sử dụng (NSUserTrackingUsageDescription) cùng với thông điệp văn bản mà bạn muốn hiển thị cho người dùng. Thư viện này chỉ có sẵn trong iOS 14.0 trở lên.
Để sử dụng tính năng Apple Search Ads Attribution, vui lòng đảm bảo đã nâng cấp lên phiên bản v1.12.6 trở lên và thêm thư viện AdServices.framework. Thư viện này chỉ có sẵn trong iOS 14.3 trở lên.

Tích hợp SDK #

Cocoapods #

Nếu bạn sử dụng pods, hãy thêm pod 'TenjinSDK' vào tệp Podfile của bạn, sau đó chạy lệnh pod Install và chuyển sang bước 4.

Trình quản lý gói Swift #

Nếu bạn sử dụng SPM, hãy thêm gói SDK của Tenjin qua Xcode bằng kho lưu trữ này [tại đây][43] và chuyển thẳng sang bước 4.

Tải xuống phiên bản SDK mới nhất [tại đây][21].
Kéo TenjinSDK.xcframework và TenjinSDK.h vào dự án của bạn trong phần “Build Phases” -> “Link Binary With Libraries”.
Hãy thêm các tham số liên kết -ObjC vào phần Cài đặt Xây dựng của bạn

Các bước thực hiện dự án Objective-C #

Hãy mở tệp AppDelegate của bạn; theo mặc định là AppDelegate.m, và #import "TenjinSDK.h".
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.

Trong phương thức didFinishLaunchingWithOptions của bạn, hãy thêm:

Objective-C

[TenjinSDK initialize:@"<sdk_key>"];
[TenjinSDK connect];

[TenjinSDK initialize:@""];
[TenjinSDK connect];

Để bật nhật ký gỡ lỗi của Tenjin iOS SDK, hãy thêm:

Objective-C

[TenjinSDK debugLogs];

[TenjinSDK debugLogs];

Dưới đây là một ví dụ về cách tích hợp trong các dự án Objective-C của bạn nên trông như thế nào trong tệp AppDelegate.m:

Objective-C

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [TenjinSDK initialize:@"<SDK_KEY>"];
    [TenjinSDK connect];

    //All your other stuff
    ...
}

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [TenjinSDK initialize:@"<SDK_KEY>"];
    [TenjinSDK connect];

    //All your other stuff
    ...
}

Các bước thực hiện dự án Swift #

Thêm tệp tiêu đề cầu nối Objective-C cho các dự án Swift. Nếu dự án của bạn chưa có tệp tiêu đề cầu nối, hãy tạo một tệp như sau:
1. Tạo một tệp tiêu đề
  1. Tệp -> Mới -> Tệp -> “Nguồn”
  2. Chọn tệp “Header” – > Nhấp vào “Tiếp theo”
  3. Tên tệp tiêu đề phải là “YourProjectName-Bridging-Header” – Trong phần “Targets” -> Chọn mục tiêu ứng dụng -> Nhấp vào Next
2. Trong tệp tiêu đề – “YourProjectName-Bridging-Header.h”
  1. Thêm nội dung sau đây: #import "TenjinSDK.h"
  2. Chuyển đến mục “App Target” và trong phần “Build Settings”
    1. Chuyển đến phần “Trình biên dịch Swift – Chung”
    2. Chuyển đến tiểu mục “Objective-C Bridging Header” và kéo tệp header – “YourProjectName-Bridging-Header.h” vào trường đó.
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.

a. Trong phương thức didFinishLaunchingWithOptions của bạn, hãy thêm:

Swift

TenjinSDK.getInstance("<sdk_key>")
TenjinSDK.connect()

TenjinSDK.getInstance("")
TenjinSDK.connect()

Nếu bạn đang sử dụng Swift 5, hãy dùng phương thức getInstance() thay vì init(). Hãy tham khảo ứng dụng Swift mẫu của chúng tôi

Để bật nhật ký gỡ lỗi của Tenjin iOS SDK, hãy thêm:

Swift

TenjinSDK.debugLogs();

TenjinSDK.debugLogs();

Dưới đây là một ví dụ về cách tích hợp trong các dự án Swift của bạn nên trông như thế nào trong tệp AppDelegate.swift:

Swift

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Override point for customization after application launch.
    TenjinSDK.getInstance("<SDK_KEY>")
    TenjinSDK.connect()
    return true
}

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // Override point for customization after application launch.
    TenjinSDK.getInstance("<SDK_KEY>")
    TenjinSDK.connect()
    return true
}

LƯU Ý: Vui lòng đảm bảo rằng bạn triển khai đoạn mã này trên mọi sự kiện didFinishLaunchingWithOptions, chứ không chỉ khi ứng dụng được mở lần đầu tiên.

Khởi tạo thay thế để xử lý các liên kết sâu từ các dịch vụ khác. Nếu bạn sử dụng các dịch vụ khác để tạo ra các liên kết sâu hoãn lại, bạn có thể chuyển các liên kết sâu đó cho Tenjin để xử lý logic ghi nhận nguồn (Attribution) cùng với các liên kết sâu đã được kích hoạt trên Tenjin của bạn.

Objective-C

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

    [TenjinSDK init:@"<SDK_KEY>"];

    //get your deep link from your other 3rd party service
    NSURL *url = [NSURL withString: @"your_deep_link"];

    //if you have a deep link that's generated from a third party service then pass it to tenjin to handle the Attribution of deep links holistically
    if(url) {
      [TenjinSDK connectWithDeferredDeeplink:url];
    }
    else{
      [TenjinSDK connect];
    }

    //All your other stuff
    //...
}

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

    [TenjinSDK init:@"<SDK_KEY>"];

    //get your deep link from your other 3rd party service
    NSURL *url = [NSURL withString: @"your_deep_link"];

    //if you have a deep link that's generated from a third party service then pass it to tenjin to handle the Attribution of deep links holistically
    if(url) {
      [TenjinSDK connectWithDeferredDeeplink:url];
    }
    else{
      [TenjinSDK connect];
    }

    //All your other stuff
    //...
}

Bạn có thể kiểm tra xem quá trình tích hợp có hoạt động bình thường hay không thông qua 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:

Khởi tạo Tenjin bằng ATTrackingManager #

Bắt đầu từ phiên bản iOS 14, bạn có thể hiển thị thông báo yêu cầu quyền ban đầu ATTrackingManager và cho phép người dùng chọn tham gia hoặc từ chối.
Nếu thiết bị không chấp nhận quyền theo dõi, IDFA sẽ trở thành 0. Nếu thiết bị chấp nhận quyền theo dõi, phương thức connect() sẽ gửi IDFA đến máy chủ của chúng tôi.
Bạn vẫn có thể gọi phương thức 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 đến Tenjin.

Objective-C

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

    [TenjinSDK init:@"<SDK_KEY>"];

    if (@available(iOS 14, *)) {
        [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
            [TenjinSDK connect];
        }];
    } else {
        [TenjinSDK connect];
    }
}

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

    [TenjinSDK init:@"<SDK_KEY>"];

    if (@available(iOS 14, *)) {
        [ATTrackingManager requestTrackingAuthorizationWithCompletionHandler:^(ATTrackingManagerAuthorizationStatus status) {
            [TenjinSDK connect];
        }];
    } else {
        [TenjinSDK connect];
    }
}

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][24] quy định về cách sử dụng và thông điệp đượ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 để xác định các yêu cầu pháp lý đối với doanh nghiệp và quy trình của quý vị, cũng như cách thức tuân thủ các yêu cầu đó.

SKAdNetwork và 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(\_:) Bạn sẽ cung cấp một số nguyên nằm trong khoảng từ 0 đến 63 (giá trị thập phân, không phải nhị phân). Giá trị này cần phản ánh trực tiếp một sự kiện trong ứng dụng hoặc cột mốc của người dùng dựa trên chiến lược giá trị chuyển đổi cụ thể mà bạn thiết lập cho ứng dụng của mình. Chúng tôi khuyến nghị mạnh mẽ bạn nên tham khảo [trang này][25] để lập kế hoạch triển khai giá trị chuyển đổi trước khi viết mã cho logic này.

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.

Objective-C

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [TenjinSDK initialize:@"<SDK_KEY>"];
    [TenjinSDK connect];

    //
    // This will call [SKAdNetwork updatePostbackConversionValue: <Integer between 0 and 63>]
    // and also send conversion value to our servers.
    //
    // You will need to use a value between 0-63.
    //
    [TenjinSDK updatePostbackConversionValue:<Integer between 0 and 63>];

    // For iOS 16.1+ (SKAN 4.0)
    [TenjinSDK updatePostbackConversionValue:<Integer between 0 and 63> coarseValue:@"medium"];
    [TenjinSDK updatePostbackConversionValue:<Integer between 0 and 63> coarseValue:@"medium" lockWindow:true];
}

@end

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{
    [TenjinSDK initialize:@"<SDK_KEY>"];
    [TenjinSDK connect];

    //
    // This will call [SKAdNetwork updatePostbackConversionValue: <Integer between 0 and 63>]
    // and also send Conversion value to our servers.
    //
    // You will need to use a value between 0-63.
    //
    [TenjinSDK updatePostbackConversionValue:<Integer between 0 and 63>];

    // For iOS 16.1+ (SKAN 4.0)
    [TenjinSDK updatePostbackConversionValue:<Integer between 0 and 63> coarseValue:@"medium"];
    [TenjinSDK updatePostbackConversionValue:<Integer between 0 and 63> coarseValue:@"medium" lockWindow:true];
}

@end

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 [phản hồi từ SK Ad Network][26] của bạn, hãy thực hiện như sau:

Chọn Info.plist trong trình duyệt Dự án (Project navigator) trong Xcode.
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.
Nhập tên khóa NSAdvertisingAttributionReportEndpoint.
Chọn “String” từ menu thả xuống trong cột “Type”.
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 đây.

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ý:

Objective-C

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

  [TenjinSDK initialize:@"<SDK_KEY>"];

  if ([self checkOptInValue]) {
      [TenjinSDK optIn];
  }
  else {
      [TenjinSDK optOut];
  }

  [TenjinSDK connect];

  //All your other stuff
  //..
}

-(BOOL) checkOptInValue
{
  // check opt-in value
  // return YES; // if user opted-in
  return NO;
}

#import "TenjinSDK.h"

@implementation TJNAppDelegate

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions
{

  [TenjinSDK initialize:@"<SDK_KEY>"];

  if ([self checkOptInValue]) {
      [TenjinSDK optIn];
  }
  else {
      [TenjinSDK optOut];
  }

  [TenjinSDK connect];

  //All your other stuff
  //..
}

-(BOOL) checkOptInValue
{
  // check opt-in value
  // return YES; // if user opted-in
  return NO;
}

Để 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 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 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 tham số bắt buộc này, sự kiện sẽ không được xử lý hoặc ghi lại.
- developer_device_id

Nếu bạn có ý định sử dụng Google Ads, bạn cũng cần thêm: advertising_id, developer_device_id, platform, os_version,app_version, locale, device_model, và build_id.

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 tôi sẽ chỉ lấy các tham số liên quan đến thiết bị sau: ip_address, advertising_id, developer_device_id, và limit_ad_tracking

Objective-C

[TenjinSDK initialize:@"<SDK_KEY>"];

NSArray *optInParams = @[@"ip_address", @"advertising_id", @"developer_device_id", @"limit_ad_tracking"];
[TenjinSDK optInParams:optInParams];

[TenjinSDK connect];

[TenjinSDK initialize:@"<SDK_KEY>"];

NSArray *optInParams = @[@"ip_address", @"advertising_id", @"developer_device_id", @"limit_ad_tracking"];
[TenjinSDK optInParams:optInParams];

[TenjinSDK 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.

Objective-C

[TenjinSDK initialize:@"<SDK_KEY>"];

NSArray *optOutParams = @[@"country", @"timezone", @"language"];
[TenjinSDK optOutParams:optOutParams];

[TenjinSDK connect];

[TenjinSDK initialize:@"<SDK_KEY>"];

NSArray *optOutParams = @[@"country", @"timezone", @"language"];
[TenjinSDK optOutParams:optOutParams];

[TenjinSDK 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()

Objective-C

[TenjinSDK initialize:@"<SDK_KEY>"];
optInOut = [TenjinSDK optInOutUsingCMP];

[TenjinSDK initialize:@"<SDK_KEY>"];
optInOut = [TenjinSDK optInOutUsingCMP];

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

Tham số	Mô tả
địa chỉ IP	Địa chỉ IP
id_quảng_cáo	ID quảng cáo của thiết bị
id_thiết_bị_nhà_phát_triển	Mã số nhà cung cấp
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áo
nền tảng	nền tảng
os_version	phiên bản hệ điều hành
thiết bị	tên thiết bị
mẫu thiết bị	mẫu thiết bị
tên_mẫu_thiết_bị	thiết bị máy móc
device_cpu	Tên CPU của thiết bị
os_version_release	phiên bản hệ điều hành
build_id	ID bản dựng
địa phương	cài đặt ngôn ngữ của thiết bị
quốc gia	vùng ngôn ngữ, quốc gia
múi giờ	múi giờ

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

Chuyển đối tượng (SKPaymentTransaction *) transaction và (NSData *)receipt sau khi xác minh giao dịch mua, và sau đó bạn có thể truyền SKPaymentTransactionStatePurchased đến Tenjin cho giao dịch đã được mua:

Objective-C

//Get the NSData receipt
NSURL *receiptURL = [[NSBundle mainBundle] appStoreReceiptURL];
NSData *receiptData = [NSData dataWithContentsOfURL:receiptURL];

//Pass the transaction and the receiptData to Tenjin
[TenjinSDK transaction: transaction andReceipt: receiptData];

//Get the NSData receipt
NSURL *receiptURL = [[NSBundle mainBundle] appStoreReceiptURL];
NSData *receiptData = [NSData dataWithContentsOfURL:receiptURL];

//Pass the transaction and the receiptData to Tenjin
[TenjinSDK transaction: transaction andReceipt: receiptData];

StoreKit 2 - Mua hàng trong ứng dụng #

StoreKit 2 là một API chỉ hỗ trợ Swift. Đối với các ứng dụng sử dụng StoreKit 2, bạn có thể trích xuất biểu diễn JWS và chi tiết giao dịch:

Objective-C

import StoreKit

func handlePurchase(_ result: VerificationResult<Transaction>) async {
    switch result {
    case .verified(let transaction):
        // Get the JWS representation (SK2 receipt)
        let jwsRepresentation = transaction.jwsRepresentation

        // Extract transaction details
        let productId = transaction.productID
        let transactionId = String(transaction.id)
        let price = transaction.price ?? Decimal(0)
        let currencyCode = transaction.currency?.identifier ?? "USD"

        // Send to Tenjin
        TenjinSDK.transaction(
            withProductName: productId,
            andCurrencyCode: currencyCode,
            andQuantity: transaction.purchasedQuantity,
            andUnitPrice: NSDecimalNumber(decimal: price),
            andTransactionId: transactionId,
            andBase64Receipt: jwsRepresentation
        )

        await transaction.finish()

    case .unverified(_, _):
        // Handle unverified transaction
        break
    }
}

import StoreKit

func handlePurchase(_ result: VerificationResult<Transaction>) async {
    switch result {
    case .verified(let transaction):
        // Get the JWS representation (SK2 receipt)
        let jwsRepresentation = transaction.jwsRepresentation

        // Extract transaction details
        let productId = transaction.productID
        let transactionId = String(transaction.id)
        let price = transaction.price ?? Decimal(0)
        let currencyCode = transaction.currency?.identifier ?? "USD"

        // Send to Tenjin
        TenjinSDK.transaction(
            withProductName: productId,
            andCurrencyCode: currencyCode,
            andQuantity: transaction.purchasedQuantity,
            andUnitPrice: NSDecimalNumber(decimal: price),
            andTransactionId: transactionId,
            andBase64Receipt: jwsRepresentation
        )

        await transaction.finish()

    case .unverified(_, _):
        // Handle unverified transaction
        break
    }
}

(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 #

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.

Xin lưu ý rằng quý khách có trách nhiệm thực hiện một giao dịch đăng ký mỗi lần trong mỗi kỳ đăng ký (ví dụ: đối với gói đăng ký hàng tháng, quý khách sẽ cần thực hiện 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ử, không gửi sự kiện giao dịch cho Tenjin.

Để biết thêm thông tin về đăng ký, vui lòng tham khảo: Tài liệu của Apple về cách làm việc với đăng ký

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

QUAN TRỌNG: KHÔNG GỬI CÁC SỰ KIỆN TÙY CHỈNH TRƯỚC KHI XẢY RA SỰ KIỆN CONNECT/INITIALIZATION (như trên). Quá trình khởi tạo phải diễn ra trước khi gửi bất kỳ sự kiện tùy chỉnh nào.

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.

Bạn cũng có thể sử dụng Tenjin SDK để truyền một sự kiện tùy chỉnh:

sendEventWithName: (NSString *)eventName và

Bạn có thể sử dụng các tính năng này để truyền các tương tác tùy chỉnh của Tenjin với ứng dụng của mình, nhằm liên kết chúng với chi phí trên mỗi người dùng từ từng nguồn thu hút người dùng mà bạn sử dụng thông qua nền tảng Tenjin. Dưới đây là một số ví dụ về cách sử dụng:

Objective-C

//send a particular event for when someone swipes on a part of your app
[TenjinSDK sendEventWithName:@"swipe_right"];

//send a particular event for when someone swipes on a part of your app
[TenjinSDK sendEventWithName:@"swipe_right"];

Các sự kiện tùy chỉnh cũng có thể truyền tham số NSInteger eventValue. Tenjin sẽ sử dụng eventValue này làm số lượng hoặc tổng cho tất cả các sự kiện tùy chỉnh có cùng eventName. eventValue PHẢI LÀ MỘT SỐ NGUYÊN. Nếu eventValue không phải là số nguyên, chúng tôi sẽ không gửi sự kiện.

Objective-C

//send a particular event for when someone swipes and an event value on a part of your app
[TenjinSDK sendEventWithName:@"swipe_right" andEventValue:@"1"];

//send a particular event for when someone swipes and an event value on a part of your app
[TenjinSDK sendEventWithName:@"swipe_right" andEventValue:@"1"];

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 (yêu cầu DataVault) #

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, thì phiên bản ứng dụng sẽ được hiển thị 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.

Objective-C

[TenjinSDK initialize:@"<sdk_key>"];
[TenjinSDK appendAppSubversion:@8888];
[TenjinSDK connect];

[TenjinSDK initialize:@""];
[TenjinSDK appendAppSubversion:@8888];
[TenjinSDK connect];

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
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 lần hiển thị quảng cáo cho người dùng. Bạn có thể truy cập hướng dẫn tích hợp tại đây.

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 đến từ nguồn truy cập tự nhiên và người dùng B đến từ Meta, đồng thời 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(userId: "user_id") getCustomerUserId()

Objective-C

[TenjinSDK initialize:@"<SDK_KEY>"];
[TenjinSDK setCustomerUserId:@"user_id"];
userId = [TenjinSDK getCustomerUserId];

[TenjinSDK initialize:@"<SDK_KEY>"];
[TenjinSDK setCustomerUserId:@"user_id"];
userId = [TenjinSDK 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()

Objective-C

[TenjinSDK initialize:@"<sdk_key>"];
analyticsId = [TenjinSDK getAnalyticsInstallationId];

[TenjinSDK initialize:@""];
analyticsId = [TenjinSDK getAnalyticsInstallationId];

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

Tenjin SDK tự động theo dõi các chỉ số tương tác của người dùng để giúp bạn hiểu rõ hơn về hành vi của người chơi và giá trị trọn đời của họ. Các chỉ số này được thu thập tự động và có thể truy cập thông qua lập trình.

Theo dõi tự động #

SDK sẽ tự động theo dõi:

Chỉ số phiên: Số phiên, thời lượng, ngày bắt đầu và ngày kết thúc của phiên
Mua hàng trong ứng dụng (IAP): Số lượng giao dịch, doanh thu theo loại tiền tệ, mã sản phẩm đã mua
Doanh thu quảng cáo (ILRD): Doanh thu theo lượt hiển thị từ các mạng quảng cáo được hỗ trợ

Truy xuất dữ liệu hồ sơ người dùng #

Lấy đối tượng hồ sơ đầy đủ #

Trả về một đối tượng TJNUserProfileData chứa tất cả các chỉ số:

Objective-C

TJNUserProfileData *profile = [TenjinSDK getUserProfile];

// Session metrics
NSInteger sessionCount = profile.sessionCount;
long long totalTime = profile.totalSessionTime;
long long avgLength = profile.averageSessionLength;
long long lastSession = profile.lastSessionLength;
long long currentSession = profile.currentSessionDuration;
NSDate *firstSession = profile.firstSessionDate;
NSDate *lastSession = profile.lastSessionDate;

// IAP metrics
NSInteger iapCount = profile.iapTransactionCount;
NSDictionary *revenueByCurrency = profile.iapRevenueByCurrency;
NSArray *productIDs = profile.purchasedProductIDsArray;

// ILRD metrics
double totalAdRevenue = profile.totalILRDRevenueUSD;
NSDictionary *revenueByNetwork = profile.ilrdRevenueByNetwork;

TJNUserProfileData *profile = [TenjinSDK getUserProfile];

// Session metrics
NSInteger sessionCount = profile.sessionCount;
long long totalTime = profile.totalSessionTime;
long long avgLength = profile.averageSessionLength;
long long lastSession = profile.lastSessionLength;
long long currentSession = profile.currentSessionDuration;
NSDate *firstSession = profile.firstSessionDate;
NSDate *lastSession = profile.lastSessionDate;

// IAP metrics
NSInteger iapCount = profile.iapTransactionCount;
NSDictionary *revenueByCurrency = profile.iapRevenueByCurrency;
NSArray *productIDs = profile.purchasedProductIDsArray;

// ILRD metrics
double totalAdRevenue = profile.totalILRDRevenueUSD;
NSDictionary *revenueByNetwork = profile.ilrdRevenueByNetwork;

Các bất động sản hiện có:

Tài sản	Loại	Mô tả
`sessionCount`	`NSInteger`	Tổng số phiên
`totalSessionTime`	`long long`	Tổng thời gian tính bằng mili giây
`averageSessionLength`	`long long`	Thời gian trung bình của mỗi phiên (tính bằng mili giây)
`lastSessionLength`	`long long`	Phiên làm việc gần nhất đã hoàn tất (tính bằng mili giây)
`currentSessionDuration`	`long long`	Thời gian phiên hiện tại đang hoạt động (tính bằng mili giây)
`firstSessionDate`	`NSDate?`	Ngày diễn ra phiên họp đầu tiên
`lastSessionDate`	`NSDate?`	Ngày kết thúc phiên làm việc gần nhất
`iapTransactionCount`	`NSInteger`	Tổng số IAP
`iapRevenueByCurrency`	`NSDictionary<NSString, NSNumber>`	Doanh thu theo mã tiền tệ
`purchasedProductIDsArray`	`NSArray<NSString*>`	Mã sản phẩm đã được sắp xếp
`totalILRDRevenueUSD`	`double`	Tổng doanh thu quảng cáo (USD)
`ilrdRevenueByNetwork`	`NSDictionary<NSString, NSNumber>`	Doanh thu quảng cáo theo mạng

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

Trả về một từ điển chứa tất cả các chỉ số để dễ dàng chuyển đổi thành định dạng chuỗi hoặc hiển thị:

Objective-C

NSDictionary *profileDict = [TenjinSDK getUserProfileAsDictionary];

// Example usage
NSNumber *sessionCount = profileDict[@"session_count"];
NSString *firstSession = profileDict[@"first_session_date"];
NSDictionary *iapRevenue = profileDict[@"iap_revenue_by_currency"];
NSArray *productIds = profileDict[@"purchased_product_ids"];

NSDictionary *profileDict = [TenjinSDK getUserProfileAsDictionary];

// Example usage
NSNumber *sessionCount = profileDict[@"session_count"];
NSString *firstSession = profileDict[@"first_session_date"];
NSDictionary *iapRevenue = profileDict[@"iap_revenue_by_currency"];
NSArray *productIds = profileDict[@"purchased_product_ids"];

Các khóa từ điển (luôn có):

Chìa khóa	Loại	Mô tả
`session_count`	`NSNumber`	Tổng số phiên
`total_session_time`	`NSNumber`	Tổng thời gian (mili giây)
`average_session_length`	`NSNumber`	Thời gian trung bình mỗi phiên (mili giây)
`last_session_length`	`NSNumber`	Phiên làm việc gần nhất (mili giây)
`iap_transaction_count`	`NSNumber`	Tổng số IAP
`total_ilrd_revenue_usd`	`NSNumber`	Tổng doanh thu quảng cáo (USD)

Các khóa từ điển (Có điều kiện – chỉ khi có sẵn):

Chìa khóa	Loại	Mô tả
`first_session_date`	`NSString`	Ngày tháng theo định dạng ISO 8601
`last_session_date`	`NSString`	Ngày tháng theo định dạng ISO 8601
`current_session_length`	`NSNumber`	Thời lượng phiên hoạt động (mili giây)
`iap_revenue_by_currency`	`NSDictionary`	Bảng chuyển đổi tiền tệ → doanh thu
`purchased_product_ids`	`NSArray`	Mảng các mã sản phẩm đã được sắp xếp
`ilrd_revenue_by_network`	`NSDictionary`	Bản đồ mạng → doanh thu

Đặt lại hồ sơ #

Xóa toàn bộ dữ liệu hồ sơ người dùng (hữu ích cho việc kiểm thử hoặc khi người dùng đăng xuất):

Objective-C

[TenjinSDK resetUserProfile];

[TenjinSDK resetUserProfile];

Cấu hình phiên làm việc #

Tùy chỉnh thời gian chờ của phiên (mặc định là 30 phút):

Objective-C

TJNUserProfileManager.sessionTimeoutInterval = 600; // 10 minutes

TJNUserProfileManager.sessionTimeoutInterval = 600; // 10 minutes

Các phương thức hỗ trợ #

Lấy doanh thu theo loại tiền tệ cụ thể:

Objective-C

double usdRevenue = [profile getIAPRevenueForCurrency:@"USD"];

double usdRevenue = [profile getIAPRevenueForCurrency:@"USD"];

Lấy doanh thu ILRD cho mạng cụ thể:

Objective-C

double appLovinRevenue = [profile getILRDRevenueForNetwork:TJNAdNetworkAppLovin];

double appLovinRevenue = [profile getILRDRevenueForNetwork:TJNAdNetworkAppLovin];

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)

Objective-C

[TenjinSDK setCacheEventSetting:true];

[TenjinSDK 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:

setGoogleDMAParametersWithAdPersonalization(bool, bool)

Objective-C

[[TeninSDK sharedInstance] setGoogleDMAParametersWithAdPersonalization:adPersonalization adUserData:adUserData];

[[TeninSDK sharedInstance] setGoogleDMAParametersWithAdPersonalization:adPersonalization adUserData: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 vẫ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.

Objective-C

[TeninSDK optInGoogleDMA]; 
[TeninSDK optOutGoogleDMA];

[TeninSDK optInGoogleDMA]; 
[TeninSDK optOutGoogleDMA];

Máy chủ MCP của Tenjin: Tra cứu...

Báo cáo so sánh về khai thác doanh thu từ quảng cáo năm 2025...

Tóm tắt #

Ghi chú: #

Tích hợp SDK #

Cocoapods #

Trình quản lý gói Swift #

Các bước thực hiện dự án Objective-C #

Các bước thực hiện dự án Swift #

Khởi tạo Tenjin bằng ATTrackingManager #

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

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

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

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 #

GDPR #

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

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

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

StoreKit 2 - Mua hàng trong ứng dụng #

Gói đăng ký IAP #

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

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

Tham số Subversion của ứng dụng dành cho thử nghiệm A/B (yêu cầu DataVault) #

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

Chiến dịch LiveOps #

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

ID cài đặt Analytics #

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

Theo dõi tự động #

Truy xuất dữ liệu hồ sơ người dùng #

Lấy đối tượng hồ sơ đầy đủ #

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

Đặt lại hồ sơ #

Cấu hình phiên làm việc #

Các phương thức hỗ trợ #

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

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

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

Chương trình khuyến khích ứng dụng di động của Thổ Nhĩ Kỳ: Danh sách kiểm tra hồ sơ đăng ký của bạn

Hướng dẫn về Chương trình khuyến khích phát triển ứng dụng di động của Thổ Nhĩ Kỳ (2026)

Cách sử dụng trợ lý AI để tích hợp Tenjin SDK: Hướng dẫn dành cho nhà phát triển

Chặn lưu lượng truy cập độc hại: Cách Snake.io giảm 33% yêu cầu gian lận