دریافت اطلاعات ارجاع نصب از مایکت

SDK ارجاع نصب مایکت به برنامهٔ Android کمک می‌کند مقدار referrer ثبت‌شده هنگام بازشدن صفحهٔ برنامه در مایکت و زمان‌های کلیک و شروع نصب را دریافت کند. برای نمونهٔ کامل و قابل اجرا، مخزن myketstore/referrer-sample را ببینید.

فایل متنی برای LLMها

دریافت فایل llm.txt — خلاصهٔ انگلیسی API، راه‌اندازی و نکات مهم این راهنما.

پیش‌نیازها

• این SDK برای برنامه‌های Android است و به نصب بودن برنامهٔ مایکت نیاز دارد.
• نسخهٔ مایکت باید versionCode برابر یا بزرگ‌تر از 1030 داشته باشد. SDK نسخه را بررسی می‌کند و اگر مایکت نصب نباشد یا قدیمی‌تر باشد، FEATURE_NOT_SUPPORTED برمی‌گرداند.
• نسخهٔ SDK استفاده‌شده در نمونه ir.myket:referrersdk:1.0.3 است.
• نمونهٔ مخزن از minSdk 21، compileSdk 37، targetSdk 36 و Java/Kotlin 17 استفاده می‌کند. این مقادیر تنظیمات همان نمونه‌اند؛ برای تنظیمات پروژهٔ خود، سازگاری نسخه‌های ابزار ساخت را جداگانه بررسی کنید.

افزودن مخزن و وابستگی

مخزن Maven مایکت را در بخش dependencyResolutionManagement فایل settings.gradle.kts اضافه کنید:

dependencyResolutionManagement {
    repositories {
        maven { setUrl("https://maven.myket.ir") }
        google()
        mavenCentral()
    }
}

سپس وابستگی SDK را به dependencies در فایل app/build.gradle.kts اضافه کنید:

dependencies {
    implementation("ir.myket:referrersdk:1.0.3")
}

مجوز و package visibility

کتابخانه این موارد را در Manifest خود اعلام می‌کند و معمولاً Android Manifest Merger آن‌ها را به برنامه اضافه می‌کند. Manifest نهایی را بررسی کنید؛ در صورت نیاز، این اعلان‌ها را در AndroidManifest.xml برنامه قرار دهید:

<uses-permission android:name="ir.mservices.market.INSTALL_REFERRER" />

<queries>
    <package android:name="ir.mservices.market" />
</queries>

دریافت اطلاعات ارجاع نصب

startConnection اتصال را به‌صورت غیرهم‌زمان آغاز می‌کند. SDK ابتدا برای اتصال از AIDL استفاده می‌کند و اگر موفق نشود، به روش Broadcast بازگشت می‌کند. چون خواندن اطلاعات در روش جایگزین ممکن است تا دریافت پاسخ یا پایان مهلت انتظار مسدود بماند، getInstallReferrer() را روی نخ پس‌زمینه اجرا کنید.

import ir.myket.referrersdk.api.InstallReferrerResponse
import ir.myket.referrersdk.api.InstallReferrerStateListener
import ir.myket.referrersdk.api.MyketReferrerClient
import java.util.concurrent.Executors

val client = MyketReferrerClient.newBuilder(context).build()
val executor = Executors.newSingleThreadExecutor()

client.startConnection(object : InstallReferrerStateListener {
    override fun onInstallReferrerSetupFinished(responseCode: Int) {
        if (responseCode != InstallReferrerResponse.OK) {
            // Handle NOT_FOUND, DEVELOPER_ERROR, FEATURE_NOT_SUPPORTED,
            // SERVICE_DISCONNECTED, or another error as appropriate.
            client.endConnection()
            executor.shutdown()
            return
        }

        executor.execute {
            try {
                val details = client.getInstallReferrer()
                val referrer = details.installReferrer
                val clickTimeSeconds = details.referrerClickTimestampSeconds
                val installBeginTimeSeconds = details.installBeginTimestampSeconds

                // Attribute this install and persist the result in your app.
            } catch (error: Exception) {
                // Handle read failures and retry only when appropriate.
            } finally {
                client.endConnection()
                executor.shutdown()
            }
        }
    }

    override fun onInstallReferrerServiceDisconnected() {
        // If you still need the data, create a new client and reconnect.
    }
})

برای هر تلاش، یک client جدید بسازید؛ endConnection() اتصال را می‌بندد. نتیجه را پس از دریافت در برنامه ذخیره کنید و منطق ثبت انتساب را در برابر پردازش تکراری مقاوم نگه دارید.

مقادیر بازگشتی

getInstallReferrer() یک ReferrerDetails برمی‌گرداند. زمان‌ها Unix timestamp بر حسب ثانیه هستند؛ مقدار 0 یعنی زمان مربوطه در دسترس نیست.

ویژگی	توضیح
installReferrer	رشتهٔ referrer ثبت‌شده از لینک صفحهٔ برنامه؛ ممکن است خالی باشد.
referrerClickTimestampSeconds	زمان بازشدن صفحهٔ برنامه در مایکت، بر حسب ثانیه.
installBeginTimestampSeconds	زمان شروع نصب، بر حسب ثانیه.

کدهای وضعیت اتصال:

کد	ثابت	معنی
0	OK	اتصال برقرار است و می‌توانید اطلاعات را بخوانید.
6	NOT_FOUND	برای برنامهٔ فراخواننده رکورد ارجاعی پیدا نشد.
5	DEVELOPER_ERROR	برنامه مجاز به خواندن رکورد درخواستی نیست. مایکت فقط اطلاعات مربوط به بستهٔ متعلق به UID فراخواننده را برمی‌گرداند.
1	FEATURE_NOT_SUPPORTED	مایکت نصب نیست، نسخهٔ آن پایین‌تر از حداقل لازم است یا سرویس در دسترس نیست.
-1	SERVICE_DISCONNECTED	اتصال سرویس قطع شده یا خطای غیرمنتظره رخ داده است.

آزمایش با پروژهٔ نمونه

برای تست روی دستگاهی که مایکت روی آن نصب است:

1. صفحهٔ برنامهٔ نمونه را با یک مقدار referrer باز کنید. می‌توانید از صفحهٔ نمونه در مایکت یا لینک زیر استفاده کنید:

   myket://details?id=ir.myket.referrersample&referrer=my-referrer

   لینک وب معادل:

   https://myket.ir/app/ir.myket.referrersample?referrer=my-referrer

   برای بازکردن لینک با ADB:

   adb shell am start -a android.intent.action.VIEW -d "myket://details?id=ir.myket.referrersample&referrer=my-referrer"

2. برنامه را از مایکت نصب کنید؛ نصب مستقیم APK یا sideload کردن، مسیر ثبت ارجاع نصب از مایکت را آزمایش نمی‌کند.

3. برنامه را اجرا کنید و Fetch referrer را بزنید. نمونه مقدار install_referrer و زمان‌های کلیک و شروع نصب را نمایش می‌دهد؛ اگر زمان در دسترس نباشد، مقدار آن صفر است.

انتشار و R8/ProGuard

نمونهٔ مخزن برای build محلی دستور ./gradlew assembleDebug را ارائه می‌کند. اگر در build انتشار minification فعال است، قواعد زیر را به فایل ProGuard/R8 برنامه اضافه کنید تا رابط AIDL حذف یا تغییرنام داده نشود:

-keep interface com.myket.installreferrer.** { *; }
-keep class com.myket.installreferrer.** { *; }

توجه

رشتهٔ ارجاع را مطابق نیاز برنامه اعتبارسنجی و امن ذخیره کنید. این SDK دادهٔ انتساب را برای برنامهٔ نصب‌شده از طریق مایکت فراهم می‌کند؛ نصب sideload‌شده یا رکورد ثبت‌نشده ممکن است NOT_FOUND برگرداند.