expo-tiktok-ads-events 0.1.2 → 0.1.4

package/CLAUDE.md

@@ -0,0 +1,87 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+This is an Expo native module that wraps the TikTok Business SDK for both iOS and Android, enabling event tracking for TikTok advertising campaigns in React Native/Expo apps.
+
+## Commands
+
+```bash
+# Build TypeScript
+npm run build
+
+# Clean build artifacts
+npm run clean
+
+# Lint code
+npm run lint
+
+# Run tests
+npm run test
+
+# Prepare for publishing
+npm run prepare
+
+# Open iOS project in Xcode
+npm run open:ios
+
+# Open Android project in Android Studio
+npm run open:android
+```
+
+## Architecture
+
+### Native Module Structure
+
+The module exports a native module named `TiktokAdsEvents` (not `ExpoTiktokAdsEvents`). Both platforms must use this exact name.
+
+```
+src/
+├── index.ts                    # Public exports
+└── ExpoTiktokAdsEventsModule.ts # TypeScript interface and helpers
+
+ios/
+├── ExpoTiktokAdsEvents.podspec  # CocoaPods spec (uses TikTokBusinessSDK)
+└── ExpoTiktokAdsEventsModule.swift # iOS implementation
+
+android/
+├── build.gradle                 # Gradle config (uses JitPack SDK)
+└── src/main/java/expo/modules/tiktokadsevents/
+    └── ExpoTiktokAdsEventsModule.kt # Android implementation
+```
+
+### Key Implementation Details
+
+- **Module Name**: Must be `TiktokAdsEvents` in both `Name()` definitions
+- **iOS SDK**: `TikTokBusinessSDK` via CocoaPods
+- **Android SDK**: `com.github.tiktok:tiktok-business-android-sdk` via JitPack
+- **Event Properties**: Passed as `List<Map<String, Any>>` (Android) or `[[String: Any]]` (iOS)
+
+### TypeScript Interface
+
+All native methods are async and must match this interface:
+- `initializeSdk(accessToken, appId, tiktokAppId, debugModeEnabled)` → `Promise<boolean>`
+- `trackTTEvent(name, properties?)` → `Promise<string>`
+- `trackCustomEvent(eventName, eventID, properties?)` → `Promise<void>`
+- `identify(externalId, externalUserName?, phoneNumber?, email?)` → `Promise<void>`
+- `getAnonymousID()` → `Promise<string>`
+- `getAccessToken()` → `Promise<string>`
+- `getTestEventCode()` → `Promise<string>`
+
+## Testing in Consumer Apps
+
+After making changes, consumer apps need:
+```bash
+npx expo prebuild --clean
+```
+
+For Android, ensure the app's `android/build.gradle` includes JitPack:
+```groovy
+allprojects {
+    repositories {
+        maven { url 'https://jitpack.io' }
+    }
+}
+```

package/README.md

@@ -10,8 +10,60 @@ npm install expo-tiktok-ads-events
 yarn add expo-tiktok-ads-events
 ```
 
+### Peer Dependencies
+
+```bash
+npm install expo-tracking-transparency
+# or
+yarn add expo-tracking-transparency
+```
+
 ## Setup
 
+### iOS Configuration
+
+#### SKAdNetwork Configuration
+
+Add the following to your `app.json` to enable proper attribution for TikTok Ads:
+
+```json
+{
+  "expo": {
+    "ios": {
+      "infoPlist": {
+        "SKAdNetworkItems": [
+          {"SKAdNetworkIdentifier": "238da6jt44.skadnetwork"},
+          {"SKAdNetworkIdentifier": "22mmun2rn5.skadnetwork"},
+          // ... add all required SKAdNetwork IDs
+          // Full list available in the example app
+        ]
+      }
+    }
+  }
+}
+```
+
+> **Note:** The complete list of 150+ SKAdNetwork IDs is available in the [example app.json](./example/app.json). These IDs are required for proper attribution of TikTok Ads campaigns.
+
+#### Tracking Permission
+
+Add to your `app.json`:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "expo-tracking-transparency",
+        {
+          "userTrackingPermission": "This identifier will be used to deliver personalized ads to you."
+        }
+      ]
+    ]
+  }
+}
+```
+
 ### Initialization
 
 ```typescript
@@ -24,11 +76,13 @@ const { status } = await requestTrackingPermissionsAsync();
 // Initialize SDK
 await TiktokAdsEvents.initializeSdk(
   'YOUR_ACCESS_TOKEN',  // TikTok Ads Manager access token
-  'YOUR_APP_ID',        // App ID
+  'YOUR_APP_ID',        // App ID  
   'YOUR_TIKTOK_APP_ID'  // TikTok App ID
 );
 ```
 
+> **Important:** Get your credentials from [TikTok Ads Manager](https://ads.tiktok.com/)
+
 ## Usage
 
 ### Standard Events
@@ -198,15 +252,20 @@ export default function App() {
 
 ### Common Properties
 
-- `currency` - Currency code (e.g., "USD", "EUR")
+- `currency` - Currency code (e.g., "USD", "EUR", "BRL")
 - `value` - Monetary value
-- `content_type` - Content type
-- `content_id` - Content ID
+- `content_type` - Content type (e.g., "product", "subscription")
+- `content_id` - Content ID or SKU
 - `content_name` - Content name
+- `content_category` - Content category
 - `quantity` - Quantity
 - `description` - Description
 - `query` - Search query
-- `status` - Status
+- `status` - Status (e.g., "success", "failed")
+- `level` - Level achieved (for gaming apps)
+- `score` - Score value
+- `success` - Success flag (boolean as string: "true"/"false")
+- `payment_method` - Payment method used
 
 ### TypeScript Types
 
@@ -244,12 +303,16 @@ The SDK is automatically configured with:
 - ✅ Retention tracking enabled
 - ✅ SKAdNetwork enabled (iOS)
 - ✅ Debug mode enabled (development)
+- ✅ Install tracking enabled
+- ✅ Auto tracking disabled (manual control)
 
-## Compatibility
+## Requirements
 
 - iOS 15.1+
 - Android (in development)
 - Expo SDK 54+
+- TikTok Business SDK
+- expo-tracking-transparency (for iOS 14+)
 
 ## Troubleshooting
 
@@ -259,6 +322,8 @@ The SDK is automatically configured with:
 2. Confirm credentials are correct
 3. Use test mode to validate events
 4. Wait up to 24 hours for production events to appear
+5. Ensure SKAdNetwork IDs are properly configured
+6. Check that the app is running on a real device (not simulator)
 
 ### Empty Anonymous ID
 
@@ -267,23 +332,31 @@ Anonymous ID is generated after successful initialization. Make sure to call `in
 ### Initialization Error
 
 Check:
-- Valid access token
-- Correct app IDs
+- Valid access token from TikTok Ads Manager
+- Correct app IDs (both App ID and TikTok App ID)
 - Internet connection
+- TikTok Business SDK is properly installed via CocoaPods
+
+### SKAdNetwork Attribution Issues
+
+- Ensure all required SKAdNetwork IDs are added to `app.json`
+- Run `npx expo prebuild` after adding SKAdNetwork configuration
+- Test on a real device (attribution doesn't work on simulator)
 
 ## API Reference
 
 ### Methods
 
-#### `initializeSdk(accessToken, appId, tiktokAppId)`
+#### `initializeSdk(accessToken, appId, tiktokAppId, debugMode?)`
 Initialize the TikTok Business SDK.
 
 **Parameters:**
 - `accessToken` (string): TikTok Ads Manager access token
 - `appId` (string): Your app ID
 - `tiktokAppId` (string): TikTok app ID
+- `debugMode` (boolean): Enable debug mode (optional, default: true in development)
 
-**Returns:** Promise<string>
+**Returns:** Promise<string> - "initialization successful" or error message
 
 #### `trackTTEvent(eventName, properties?)`
 Track a standard TikTok event.
@@ -342,9 +415,16 @@ Bruno Verçosa - [Pixel Logic Apps](https://github.com/Pixel-Logic-Apps)
 
 Contributions are welcome! Please open an issue or submit a pull request.
 
-## Links
+## Resources
 
+### Official Documentation
 - [TikTok for Business](https://business.tiktok.com/)
 - [TikTok Ads Manager](https://ads.tiktok.com/)
+- [TikTok Events Manager](https://ads.tiktok.com/events_manager/)
 - [TikTok Events API](https://business-api.tiktok.com/portal/docs)
-- [Expo Modules Documentation](https://docs.expo.dev/modules/)
+- [TikTok Business SDK iOS](https://github.com/tiktok/tiktok-business-ios-sdk)
+
+### Related
+- [Expo Modules Documentation](https://docs.expo.dev/modules/)
+- [SKAdNetwork Documentation](https://developer.apple.com/documentation/storekit/skadnetwork)
+- [App Tracking Transparency](https://developer.apple.com/documentation/apptrackingtransparency)

package/android/build.gradle

@@ -9,6 +9,11 @@ applyKotlinExpoModulesCorePlugin()
 useCoreDependencies()
 useExpoPublishing()
 
+repositories {
+  maven { url 'https://jitpack.io' }
+  maven { url "https://artifact.bytedance.com/repository/pangle" }
+}
+
 // If you want to use the managed Android SDK versions from expo-modules-core, set this to true.
 // The Android SDK versions will be bumped from time to time in SDK releases and may introduce breaking changes in your module code.
 // Most of the time, you may like to manage the Android SDK versions yourself.
@@ -41,3 +46,7 @@ android {
     abortOnError false
   }
 }
+
+dependencies {
+  implementation 'com.github.tiktok:tiktok-business-android-sdk:1.6.0'
+}

package/android/src/main/AndroidManifest.xml

@@ -1,2 +1,5 @@
-<manifest>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.INTERNET" />
+  <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
+  <uses-permission android:name="com.google.android.gms.permission.AD_ID" />
 </manifest>

package/android/src/main/java/expo/modules/tiktokadsevents/ExpoTiktokAdsEventsModule.kt

@@ -1,50 +1,160 @@
 package expo.modules.tiktokadsevents
 
+import android.util.Log
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
-import java.net.URL
+import expo.modules.kotlin.Promise
+import com.tiktok.TikTokBusinessSdk
+import com.tiktok.TikTokBusinessSdk.TTConfig
+import com.tiktok.TikTokBusinessSdk.LogLevel
+import org.json.JSONObject
 
 class ExpoTiktokAdsEventsModule : Module() {
-  // Each module class must implement the definition function. The definition consists of components
-  // that describes the module's functionality and behavior.
-  // See https://docs.expo.dev/modules/module-api for more details about available components.
+
+  // Store accessToken since Android SDK doesn't expose it like iOS
+  private var storedAccessToken: String = ""
+
+  private val standardEventMap = mapOf(
+    "achieve_level" to "AchieveLevel",
+    "add_payment_info" to "AddPaymentInfo",
+    "complete_tutorial" to "CompleteTutorial",
+    "create_group" to "CreateGroup",
+    "create_role" to "CreateRole",
+    "generate_lead" to "GenerateLead",
+    "in_app_ad_click" to "InAppADClick",
+    "in_app_ad_impr" to "InAppADImpr",
+    "install_app" to "InstallApp",
+    "join_group" to "JoinGroup",
+    "launch_app" to "LaunchAPP",
+    "loan_application" to "LoanApplication",
+    "loan_approval" to "LoanApproval",
+    "loan_disbursal" to "LoanDisbursal",
+    "login" to "Login",
+    "rate" to "Rate",
+    "registration" to "Registration",
+    "search" to "Search",
+    "spend_credits" to "SpendCredits",
+    "start_trial" to "StartTrial",
+    "subscribe" to "Subscribe",
+    "unlock_achievement" to "UnlockAchievement"
+  )
+
+  private fun buildPropertiesJson(properties: List<Map<String, Any>>?): JSONObject? {
+    if (properties == null || properties.isEmpty()) return null
+    val json = JSONObject()
+    properties.forEach { prop ->
+      val key = prop["key"] as? String
+      val value = prop["value"]
+      if (key != null && value != null) {
+        json.put(key, value)
+      }
+    }
+    return json
+  }
+
   override fun definition() = ModuleDefinition {
-    // Sets the name of the module that JavaScript code will use to refer to the module. Takes a string as an argument.
-    // Can be inferred from module's class name, but it's recommended to set it explicitly for clarity.
-    // The module will be accessible from `requireNativeModule('ExpoTiktokAdsEvents')` in JavaScript.
-    Name("ExpoTiktokAdsEvents")
+    Name("TiktokAdsEvents")
+
+    AsyncFunction("initializeSdk") { accessToken: String, appId: String, tiktokAppId: String, debugModeEnabled: Boolean, promise: Promise ->
+      try {
+        val context = appContext.reactContext ?: throw Exception("React context is null")
+
+        // Store accessToken for later retrieval
+        storedAccessToken = accessToken
+
+        val configBuilder = TTConfig(context)
+          .setAppId(appId)
+          .setTTAppId(tiktokAppId)
+
+        if (debugModeEnabled) {
+          configBuilder.setLogLevel(LogLevel.DEBUG)
+          configBuilder.openDebugMode()
+        }
+
+        TikTokBusinessSdk.initializeSdk(configBuilder)
+        promise.resolve(true)
+      } catch (e: Exception) {
+        Log.e("TiktokAdsEvents", "Error initializing SDK: ${e.message}", e)
+        promise.reject("INIT_ERROR", e.message, e)
+      }
+    }
+
+    AsyncFunction("getAnonymousID") { promise: Promise ->
+      try {
+        // Android SDK uses getSessionID() as equivalent to iOS anonymousID
+        val sessionId = TikTokBusinessSdk.getSessionID() ?: ""
+        promise.resolve(sessionId)
+      } catch (e: Exception) {
+        promise.reject("ERROR", e.message, e)
+      }
+    }
 
-    // Defines constant property on the module.
-    Constant("PI") {
-      Math.PI
+    AsyncFunction("getAccessToken") { promise: Promise ->
+      try {
+        // Return the stored accessToken from initialization
+        promise.resolve(storedAccessToken)
+      } catch (e: Exception) {
+        promise.reject("ERROR", e.message, e)
+      }
     }
 
-    // Defines event names that the module can send to JavaScript.
-    Events("onChange")
+    AsyncFunction("getTestEventCode") { promise: Promise ->
+      try {
+        val code = TikTokBusinessSdk.getTestEventCode() ?: ""
+        promise.resolve(code)
+      } catch (e: Exception) {
+        promise.reject("ERROR", e.message, e)
+      }
+    }
 
-    // Defines a JavaScript synchronous function that runs the native code on the JavaScript thread.
-    Function("hello") {
-      "Hello world! 👋"
+    AsyncFunction("trackCustomEvent") { eventName: String, eventID: String, properties: List<Map<String, Any>>?, promise: Promise ->
+      try {
+        val propsJson = buildPropertiesJson(properties)
+        if (propsJson != null) {
+          TikTokBusinessSdk.trackEvent(eventName, propsJson)
+        } else {
+          TikTokBusinessSdk.trackEvent(eventName)
+        }
+        TikTokBusinessSdk.flush()
+        promise.resolve(null)
+      } catch (e: Exception) {
+        Log.e("TiktokAdsEvents", "Error tracking custom event: ${e.message}", e)
+        promise.reject("TRACK_ERROR", e.message, e)
+      }
     }
 
-    // Defines a JavaScript function that always returns a Promise and whose native code
-    // is by default dispatched on the different thread than the JavaScript runtime runs on.
-    AsyncFunction("setValueAsync") { value: String ->
-      // Send an event to JavaScript.
-      sendEvent("onChange", mapOf(
-        "value" to value
-      ))
+    AsyncFunction("trackTTEvent") { eventKey: String, properties: List<Map<String, Any>>?, promise: Promise ->
+      try {
+        val resolved = standardEventMap[eventKey] ?: eventKey
+        val propsJson = buildPropertiesJson(properties)
+
+        if (propsJson != null) {
+          TikTokBusinessSdk.trackEvent(resolved, propsJson)
+        } else {
+          TikTokBusinessSdk.trackEvent(resolved)
+        }
+        TikTokBusinessSdk.flush()
+
+        promise.resolve(resolved)
+      } catch (e: Exception) {
+        Log.e("TiktokAdsEvents", "Error tracking event: ${e.message}", e)
+        promise.reject("TRACK_ERROR", e.message, e)
+      }
     }
 
-    // Enables the module to be used as a native view. Definition components that are accepted as part of
-    // the view definition: Prop, Events.
-    View(ExpoTiktokAdsEventsView::class) {
-      // Defines a setter for the `url` prop.
-      Prop("url") { view: ExpoTiktokAdsEventsView, url: URL ->
-        view.webView.loadUrl(url.toString())
+    AsyncFunction("identify") { externalId: String, externalUserName: String?, phoneNumber: String?, email: String?, promise: Promise ->
+      try {
+        TikTokBusinessSdk.identify(
+          externalId,
+          externalUserName ?: "",
+          phoneNumber ?: "",
+          email ?: ""
+        )
+        promise.resolve(null)
+      } catch (e: Exception) {
+        Log.e("TiktokAdsEvents", "Error identifying user: ${e.message}", e)
+        promise.reject("IDENTIFY_ERROR", e.message, e)
       }
-      // Defines an event that the view can send to JavaScript.
-      Events("onLoad")
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-tiktok-ads-events",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Expo Tiktok SDK Events",
   "main": "build/index.js",
   "types": "build/index.d.ts",

package/android/src/main/java/expo/modules/tiktokadsevents/ExpoTiktokAdsEventsView.kt

@@ -1,30 +0,0 @@
-package expo.modules.tiktokadsevents
-
-import android.content.Context
-import android.webkit.WebView
-import android.webkit.WebViewClient
-import expo.modules.kotlin.AppContext
-import expo.modules.kotlin.viewevent.EventDispatcher
-import expo.modules.kotlin.views.ExpoView
-
-class ExpoTiktokAdsEventsView(context: Context, appContext: AppContext) : ExpoView(context, appContext) {
-  // Creates and initializes an event dispatcher for the `onLoad` event.
-  // The name of the event is inferred from the value and needs to match the event name defined in the module.
-  private val onLoad by EventDispatcher()
-
-  // Defines a WebView that will be used as the root subview.
-  internal val webView = WebView(context).apply {
-    layoutParams = LayoutParams(LayoutParams.MATCH_PARENT, LayoutParams.MATCH_PARENT)
-    webViewClient = object : WebViewClient() {
-      override fun onPageFinished(view: WebView, url: String) {
-        // Sends an event to JavaScript. Triggers a callback defined on the view component in JavaScript.
-        onLoad(mapOf("url" to url))
-      }
-    }
-  }
-
-  init {
-    // Adds the WebView to the view hierarchy.
-    addView(webView)
-  }
-}