SDK اندرويد

SDK اندرويد(Android SDK)

استفاده از SDK اندروید Zebline، شما را قادر مي سازد تا رویدادهایی را از برنامه های اندرویدی خود ردیابی کرده و به سرويس زبلاين ارسال نمایید.

الزامات راه اندازي SDK(SDK setup requirements)
برای نصب و راه اندازی SDK اندروید Zebline، مراحل زیر را دنبال کنید:

ابتدا، Android Studio را بر روی کامپیوتر خود نصب نمایید.
سپس، وارد حساب کاربري خود در Zebline، شوید.
در داشبورد، یک منبع اندروید¹ ایجاد کرده و کلید Write Key مربوط به آن را دریافت کنید، که به شما امکان می دهد رویدادها را به Zebline ارسال نماييد. همانطور که در شکل زیر نشان داده شده است:

علاوه بر این، شما به یک data plane URL نیازمند خواهید بود.
نکته: Zebline برای مسیریابی و پردازش رویدادها در Backend به data plane URL نیاز دارد. شما می توانید این URL را در صفحه اصلی داشبورد Zebline خود بیابید.
نکته: در بخش 'Setup' موجود در داشبورد Zebline (که در تصویر بالا قابل مشاهده است)، قسمتي وجود دارد که شامل کد نصب SDK است و هردو کلید write key و data plane URL در آن گنجانده شده اند. شما می توانید از این کد برای ادغام SDK اندروید در پروژه تان بهره ببرید.

نصب SDK(Installing the SDK)
از ابتدای ماه مي(1st May)، به دلیل غیرفعال شدن Bintray، SDK اندروید، به Maven Central انتقال یافته است. لازم به ذکر است که تمامی نسخه های 1.0.10 به بعد، تنها در Maven Central قابل دسترسی است.
در حال حاضر SDK اندروید، از طریق Maven Central توزیع می شود. استفاده از سیستم ساخت Android Gradle به عنوان روشی آسان و توصیه شده برای ادغام SDK در پروژه ی شما می باشد.
برای ادغام SDK اندروید در پروژه خود، مراحل زیر را دنبال کنید:

فایل build.gradle در سطح پروژه خود را باز کنید و خطوط کد زیر را به آن اضافه نمایید:

سپس فایل app/build.gradle خود را باز کرده و وابستگی مورد نظر را در زیر بخش وابستگی ها مطابق زیر اضافه کنید:

نکته: توصیه می شود از Core Android SDK بدون افزودن هیچ** device-mode SDK مقصدی استفاده کنید، تا داده های ضبط شده توسط SDK را به صورت شفاف تری مشاهده نمایید.

تنظیم مجوزهای اندروید (Setting Android permissions)
برای اعطای دسترسی به internet، خط زیر را به فایل AndroidManifest.xml در برنامه ی خود، اضافه نمایید:

همچنين، android.permission.BLUETOOTH و android.permission.ACCESS_WIFI_STATE با ذکر "false"=required به عنوان پارامترهاي اختیاری تعريف مي کنيم. اگر این مجوزها را دریافت کنیم، وضعیت Bluetooth و وضعیت WiFi دستگاه را ضبط کرده و آن را به context.network منتقل می کنیم.

قوانين Android ProGuard (Android ProGuard rules)
اگر از Proguard full mode برای بهینه سازی برنامه خود استفاده می کنید، خطوط زیر را به قوانین Android ProGuard خود اضافه نماييد:

نکته: اگر از نسخه های قدیمی تر SDK اندروید (v1.20.0) استفاده می کنید، قوانین زیر را اضافه کنید.

نکته: توجه داشته باشید که قوانین از نسخه v1.20.0 به بعد در خود SDK گنجانده شده اند.

راه اندازي کلاينت زبلاين (Initializing the Zebline client)
کتابخانه را در کلاس هایی که مایل به استفاده از کتابخانه RudderClient هستید، وارد² کنید.

کد زیر را به متد onCreate در کلاس Application خود اضافه کنید:

val rudderClient =

RudderClient.getInstance(
this,
'WRITE_KEY',
RudderConfig.Builder()
.withDataPlaneUrl('DATA_PLANE_URL')
.withControlPlaneUrl('CONTROL_PLANE_URL')
.withTrackLifecycleEvents(true)
.withRecordScreenViews(true)
.build())

پيکربندي کلاينت زبلاين(Configuring your Zebline client)
شما می توانید کلاينت خود را بر اساس روش های زیر با استفاده از RudderConfig.Builder پیکربندی کنید:

Method	Type	Description
withLogLevel	Integer	کنترل جزئیات لاگی که می خواهید با استفاده از SDK ضبط کنید. مقدار پيش فرض(Default value): RudderLogger.RudderLogLevel.NONE
withDataPlaneUrl	String	مقداردهي data plane URL تان مقدار پيش فرض(Default value): https://analytics.zebline.com
withDbThresholdCount	Integer	تعداد رویدادهایی که باید در پایگاه داده SQLite ذخیره شوند. هنگامی که حد مجاز رسیده شود، رویدادهای قدیمی تر از پایگاه داده حذف می شوند. مقدار پيش فرض(Default value): 10000
withSleepcount	Integer	حداقل زمان انتظار برای flush کردن رویدادها به سرور زبلاين. حداقل مقدار می تواند به 1 ثانیه تنظیم شود. مقدار پيش فرض(Default value): 10 ثانیه
withConfigRefreshInterval	Integer	زمانی که پس از آن، SDK تنظیمات را از داشبورد دریافت می کند. مقدار پيش فرض(Default value): 2 ساعت
withTrackLifecycleEvents	Boolean	تعیین می کند که آیا SDK باید به طور خودکار رویدادهای چرخه حیات برنامه را با استفاده از فراخوانی های چرخه حیات activity ضبط کند. مقدار پيش فرض(Default value): true
withNewLifecycleEvents	Boolean	تعیین می کند که آیا SDK باید به طور خودکار رویدادهای چرخه حیات برنامه را با استفاده از کلاس LifecycleObserver اندرویدX ضبط کند. مقدار پيش فرض(Default value): false
withTrackDeepLinks	Boolean	تعیین می کند که آیا SDK باید جزئیات خاص deep link را به عنوان رویداد Deep Link Opened ارسال کند. مقدار پيش فرض(Default value): true
withAutoSessionTracking	Boolean	تعیین می کند که آیا SDK باید به طور خودکار session کاربر را ردیابی کند. مقدار پيش فرض(Default value): true
withSessionTimeoutMillis	Integer	حداکثر دوره غيرفعال بودن قبل از انقضای session مقدار پيش فرض(Default value): 300000 میلی ثانیه (5 دقیقه)
withRecordScreenViews	Boolean	تعیین می کند که آیا SDK باید به طور خودکار رویدادهای نمایش صفحه را ضبط کند. مقدار پيش فرض(Default value): false
withGzip	Boolean	درخواست های رویداد را با Gzip فشرده می کند. مقدار پيش فرض(Default value): true
withCollectDeviceId	Boolean	تعیین می کند که آیا SDK باید به طور خودکار شناسه دستگاه را گردآوري کند. اگر به false تنظیم شود، context.device.id را به عنوان بخشی از payload رویداد ارسال نمی کند. مقدار پيش فرض(Default value): true
withAutoCollectAdvertId	Boolean	تعیین می کند که آیا SDK باید به طور خودکار شناسه تبلیغاتی را گردآوري کند. مقدار پيش فرض(Default value): false
withDbEncryption	DbEncryption	مشخص کنید که آیا باید پایگاه داده را با استفاده از کلید دلخواه خود رمزگذاری/رمزگشایی کنید.
withFlushPeriodically	Integer	به طور دوره ای رویدادها را از SDK اندروید به زبلاين flush می کند، صرف نظر از اینکه برنامه شما باز است یا خیر. مقدار پيش فرض(Default value): 15 دقیقه
withFlushQueueSize	Integer	تعداد رویدادها در یک درخواست دسته ای به سرور زبلاين. مقدار پيش فرض(Default value): 30
withControlPlaneUrl	String	withControlPlaneUrl را همراه با این URL اضافه می کند تا اطلاعات مربوط به پیکربندی resource را واکشی کند. مقدار پيش فرض(Default value): https://c.zebline.com

یک قطعه کد نمونه برای پیکربندی کلاينت شما با استفاده از RudderConfig.Builder در زیر نشان داده شده است:

رمزنگاري پايگاه داده (DbEncryption)
این ویژگی در نسخه های 1.18.0 و بالاتر SDK اندروید موجود است.

SDK اندروید از یک پایگاه داده SQLite برای ذخیره رویدادها قبل از ارسال آن ها به data plane زبلاين استفاده می کند.

شما می توانید از شیء DbEncryption جهت رمزگذاری/رمزگشایی یک پایگاه داده جدید یا موجود با کلید مشخص شده خود استفاده کنید.

افزودن وابستگی ها(Add dependencies):

از آنجا که SDK اندروید به کتابخانه SQLite Cipher وابسته است، شما باید sqlcipher-android را به عنوان یک وابستگی³ اضافه کنید:

SDK اندروید زبلاين را به عنوان یک وابستگی اضافه کنید.
به فایل build.gradle در سطح ماژول رفته و موارد زیر را در بخش وابستگی هاdependencies اضافه کنید.

تنظیم شیء رمزنگاری(Set the encryption object):

برای رمزگذاری/رمزگشایی پایگاه های داده، هنگام مقداردهی اولیه SDK اندروید، شیء DbEncryption را ایجاد و تنظیم کنید که به شرح زیر است:

متد withDbEncryption یک شیء DbEncryption را با پارامترهای زیر می پذیرد:

Parameter	Data type	Description
true/false	Boolean	مشخص می کند که آیا باید یک پایگاه داده رمزنگاری نشده را رمزگذاری کند یا یک پایگاه داده رمزگذاری شده را رمزگشایی کند.
key	String	encrypt decrypt کلیدی که جهت رمزگذاری⁴/رمزگشایی⁵ پایگاه داده استفاده مي شود.

Parameter

Data type

Description

true/false

Boolean

مشخص می کند که آیا باید یک پایگاه داده رمزنگاری نشده را رمزگذاری کند یا یک پایگاه داده رمزگذاری شده را رمزگشایی کند.

key

String

encrypt

decrypt

کلیدی که جهت رمزگذاری⁴/رمزگشایی⁵ پایگاه داده استفاده مي شود.

توجه: پس از رمزگذاری پایگاه داده:

اگر کلیدی ارائه نشود(no key)،SDK ،پایگاه داده فعلی با رویدادهای ارسال نشده را حذف کرده و به جای آن یک پایگاه داده جدید رمزنگاری نشده⁶ ایجاد می کند.
اگر کلید اشتباهی ارائه شود(wrong key)، SDK، پایگاه داده فعلی⁷ با رویدادهای ارسال نشده⁸ را حذف کرده و یک پایگاه داده جديد رمزگذاری شده⁹ با کلید داده شده ایجاد می کند.

SDK کلید را ذخیره نمی کند، بنابراین نمی تواند تشخیص دهد که کلید وارد شده صحیح است یا خیر. بنابراین، اگر کلید نتواند پایگاه داده را رمزگشایی کند، SDK آن را نادرست فرض کرده و رویدادها و پایگاه داده قدیمی را حذف می کند.

درخواست هاي Gzipping (Gzipping requests)
ویژگی Gzip به طور پیش فرض در SDK اندروید، فعال مي باشد.
SDK اندروید به طور خودکار درخواست های رویداد را با Gzip فشرده می کند. برای غیرفعال کردن این ویژگی، پارامتر Gzip را هنگام مقداردهی اولیه SDK به false تنظیم کنید:

برای استفاده از Gzip نیاز به نسخه 1.4 یا بالاتر rudder-server دارید. در غیر این صورت، رویدادهای شما با خطا مواجه شوند.

شناسایی (Identify)
فراخوانی identify به شما امکان می دهد که یک کاربر بازدیدکننده را شناسایی کرده و آنها را به اعمالشان¹⁰ مرتبط کنید. همچنین به شما اجازه می دهد تا ویژگی هایی در مورد آن ها مانند نام، آدرس ایمیل و غیره را ثبت کنید. پس از شناسایی کاربر، SDK تمام اطلاعات کاربر را حفظ کرده و آنها را به فراخوانی های track یا screen بعدی منتقل می کند. برای بازنشانی شناسایی کاربر، می توانید از متد reset استفاده کنید.
توجه داشته باشید که:
برای نسخه های قدیمی تر SDK (< v1.18.0)، SDK اندروید شناسه دستگاه را ضبط می کند و از آن به عنوان anonymousId برای شناسایی کاربر استفاده می کند که به SDK کمک می کند تا کاربران را در طول نصب برنامه ردیابی کند.
در دستگاه های اندروید، deviceId در اولین boot اختصاص داده می شود. این شناسه در طول برنامه ها و نصب ها ثابت می ماند و تنها پس از factory reset تغییر می کند.
از نسخه v1.18.0 به بعد، SDK به جای شناسه دستگاه از یک UUID به عنوان anonymousId استفاده می کند.
یک نمونه رویداد identify به شرح زیر است:

val traits = RudderTraits()

traits.putBirthday(Date())

traits.put("Email","abc@123.com")

traits.put("FirstName","alex")

traits.put("LastName","myli")

traits.put("Gender","m")

rudderClient.identify("test_user_id", traits, null)

براي فعال کردن push notification، mobile token تکميل شود

متدهای زیر را دنبال کنید:

Name	Data Type	Required	Description
traits	RudderTraits	Yes	اطلاعات ویژگی های کاربر
options	RudderOption	No	گزینه های اضافی برای رویداد شناسايي

يا

Name	Data Type	Required	Description
userId	String	Yes	شناسه توسعه دهنده برای کاربر
traits	RudderTraits	No	اطلاعات ویژگی های کاربر
option	RudderOption	No	گزینه های اضافی برای رویداد شناسايي

مقداردهي مجدد شناسه ناشناس (Overriding anonymous ID)
شما می توانید از متد زیر برای استفاده از anonymousId خودتان با SDK استفاده کنید.

یک نمونه از تنظیم anonymousId به شرح زیر است:

برای بازیابی anonymousId، می توانید از ویژگی نمونه anonymousId استفاده کنید:

غيرفعال سازي مجموعه شناسه دستگاه (Disabling device ID collection)
از نسخه v1.18.0 به بعد، شما می توانید مجموعه شناسه دستگاه را با تنظیم withCollectDeviceId API کلاس RudderConfigBuilder به false غیرفعال کنید.

شما تغییرات زیر را در صورتي که این API به false تنظیم شود، مشاهده خواهید کرد:

SDK، context.device.id را به عنوان بخشی از payload رویداد ارسال نمی کند.
SDK، anonymousId موجود را (اگر برابر با شناسه دستگاه يا device ID باشد) با یک UUID جایگزین می کند.

نکته: این تغییرات برای انطباق بیشتر SDK با تمام سیاست های مربوط به مجموعه شناسه دستگاه معرفی شده اند.

RudderClient rudderClient = RudderClient.getInstance(
        this,
        'WRITE_KEY',
        new RudderConfig.Builder()
.withDataPlaneUrl('DATA_PLANE_URL')
.withControlPlaneUrl('CONTROL_PLANE_URL')
.withCollectDeviceId(false)
.build());

اگر به آخرین نسخه SDK از یک نسخه قبلی (v1.18.0>) به روزرسانی می کنید و مجموعه شناسه دستگاه را با استفاده از withCollectDeviceId(false) غیرفعال می کنید:

مطمئن شوید که تبدیل های کاربري¹¹ به context.device.id وابسته نباشند زیرا SDK، این مقدار را در payload رویداد ارسال نمی کند.
ستون context.device.id در مقصد انبار داده شما دیگر تکميل نخواهد شد ( و همچنان شامل داده هایی است که توسط نسخه قبلی SDK پر شده اند).

چگونگی تنظیم شناسه ناشناس توسط SDK (How SDK sets anonymous ID)

برای نصب مستقیم/جدید¹² SDK:

براي نصب جدید Android SDK نسخه 1.18.0 و بعد از آن، سرويس مارکتينگ اتوماسيون Zebline از UUID به عنوان anonymousId استفاده می کند، صرف نظر از اینکه withCollectDeviceId روی true یا false تنظیم شده باشد.

برای به روزرسانی SDK از نسخه قدیمی تر:

اگر شما در حال به روزرسانی Android SDK خود از نسخه قدیمی تری هستید (کمتر از v1.18.0)، بنابراين:

همچنان Zebline، از شناسه دستگاه، به عنوان anonymousId استفاده می کند - تا زمانی که شما withCollectDeviceId را بر روی false تنظیم نکنید، عملکرد موجود SDK دستخوش تغییر نخواهد شد.
اگر شما withCollectDeviceId را بر روی false تنظیم کنید، SDK بررسی می کند که آیا anonymousId موجود، شناسه دستگاه است یا خیر. اگر پاسخ مثبت باشد، یک UUID جدید را به عنوان anonymousId تعیین می نماید.
اگر شما از متد putAnonymousId جهت تنظیم anonymousId خود استفاده کرده اید، بنابراين SDK حتی در صورتي که شما withCollectDeviceId را بر روی false تنظیم کنید، آن را تغییر نمي دهد.

تنظيم شناسه سفارشي (Setting a custom ID)
شما می توانید یک شناسه سفارشی را همراه با userId استاندارد در فراخوان های identify خود ارسال کنید. زبلاين این مقدار را در context.externalId اضافه می کند.

نکته: زبلاين تنها در رویدادهای identify از ارسال externalId پشتیبانی می کند. شما نباید این شناسه را در سایر فراخوان های API مانند track، page و غیره ارسال کنید.

قطعه کد زیر نحوه افزودن یک externalId به رویداد شناسایی شما را نشان می دهد:

rudderClient.identify(

"1hKOmRA4GRlm",

RudderTraits().put("FirstName","Alex"),

RudderOption()

.putExternalId("brazeExternalId", "some_external_id")

)

رديابي (Track)
شما می توانید فعالیت های کاربران را از طریق متد track ثبت کنید. هر عمل کاربر، یک رویداد(event) نامیده می شود.
یک نمونه رویداد track به شرح زیر است:

از امضاهای متد زیر استفاده کنید:

Name	Data Type	Required	Description
name	String	Yes	نام رویدادی که می خواهید ردیابی کنید.
property	RudderProperty or Map<String, Object>	No	ویژگی های داده ی اضافی که می خواهید همراه با رویداد ارسال کنید.
options	RudderOption	No	گزینه های اضافی رویداد

صفحه نمايش (Screen)
شما می توانید از فراخوان screen برای ثبت هر زمانی که کاربر یک صفحه را در دستگاه موبایل می بیند، استفاده کنید. شما همچنین می توانید برخی از ویژگی های اضافی را همراه با این رویداد ارسال کنید.
یک نمونه از رویداد screen به شرح زیر است:

از امضاهای متد زیر استفاده کنید:

Name	Data Type	Required	Description
screenName	String	Yes	نام صفحه ای که مشاهده شده است
category	String	No	دسته بندی صفحه ای که بازدید شده، مانند HomeScreen, LoginScreen. برای ردیابی چندین نمای Fragment تحت یک Activity مفید است.
property	RudderProperty	No	شیء ویژگی اضافی که می خواهید همراه با فراخوانی صفحه ارسال کنید.
option	RudderOption	No	گزینه های اضافی که باید همراه با رویداد صفحه ارسال شوند.

گروه (Group)
فراخوانی group، کاربر را به یک سازمان خاص مرتبط می کند. نمونه ای از فراخوانی group برای API در زیر آمده است:

از امضاهای متد زیر استفاده کنید:

Name	Data Type	Required	Description
groupId	String	Yes	شناسه ای از سازمان که می خواهید کاربر خود را با آن مرتبط کنید.
traits	RudderTraits	No	هر ویژگی دیگری از سازمان که می خواهید همراه با فراخوانی منتقل کنید
options	RudderOption	No	گزینه های سطح رویداد

نام مستعار (Alias)
فراخوانی alias به کاربر اجازه می دهد تا با یک شناسه جدید مرتبط شود. نمونه ای از فراخوانی alias برای API در زیر آمده است:

به جای آن، می توانید از امضای متد زیر استفاده کنید:

Name	Data Type	Required	Description
newId	String	Yes	شناسه کاربر جدیدی(new userId) که می خواهید به کاربر اختصاص دهید.
options	RudderOption	No	گزینه سطح رویداد

زبلاين شناسه کاربر قدیمی را با newUserId جدید جایگزین می کند و ما این شناسه را در طول جلسات حفظ می کنیم.

بازنشاني (Reset)
شما می توانید از متد reset برای حذف ویژگی های ذخیره شده ی کاربر استفاده نمایید. همچنین، اگر با مقدار 'true' فراخوانی شود (برای SDK نسخه 1.18.0 و بعد از آن)، شناسه ناشناس (anonymousId) را با یک UUID جدید جایگزین می کند. برای حذف تنها ویژگی های کاربر، متد reset را با مقدار 'false' فراخوانی کنید.
در session tracking، فراخوانی متد reset، sessionId فعلی را پاک کرده و یک session جدید ایجاد می کند.
یک نمونه فراخوانی reset به شرح زیر است:

تنظيماتGDPR (Consent-driven user tracking/GDPR support)
سرويس مارکتينگ اتوماسيون Zebline به کاربران این امکان را می دهد که تا زمانی که رضایت خود را اعلام نکرده اند، از ردیابی هرگونه فعالیت کاربری خودداری کنند. شما می توانید این کار را با استفاده از optOut API در SDK انجام دهید.
optOut API از مقادير بولین true یا false برای فعالسازي یا غیرفعالسازي ردیابی فعالیت های کاربر استفاده مي کند. این تنظيم(flag) حتی پس از راه اندازی مجدد دستگاه نيز حفظ مي شود.
قطعه کد زیر استفاده از optOut API برای غیرفعال کردن ردیابی کاربر را نشان می دهد:

زمانی که کاربر رضایت خود را اعلام کرد، شما می توانید با استفاده از optOut API و ارسال false به عنوان پارامتر، ردیابی کاربر را دوباره فعال کنید.

optOut API از نسخه v1.0.21 به بعد در SDK اندروید موجود است.

تنظيم توکن دستگاه اندرويد (Setting the Android device token)
شما می توانید device-token خود را جهت ارسال push notification به مقاصدی که از push notification پشتیبانی می کنند، مشخص نماييد. ما token را در context.device.token تنظیم می کنیم.
قطعه کد زیر را دنبال کنید:
RudderClient.put("Device_Token","your_ss")
تنظيم context سفارشي (Setting custom context)
شما می توانید اطلاعات context سفارشی را در Android SDK با استفاده از یکی از روش های زیر تنظیم کنید:
هنگام راه اندازی اولیه SDK (During SDK initialization)

در زمان راه اندازی SDK، می توانید اطلاعات context سفارشي را به شکل زیر تنظیم کنید:

این ویژگی از نسخه v1.22.0 به بعد در SDK اندروید موجود است.

لطفاً توجه داشته باشید که:

SDK اندروید اطلاعات contextيي که در زمان راه اندازی SDK تنظیم شده اند را برای رویدادهای بعدی حفظ می کند، اما این اطلاعات در sessionهاي مختلف حفظ نمی شوند.
با فراخوانی متد reset، تمامی اطلاعات contextيي که در زمان راه اندازی SDK تنظیم شده اند، پاک خواهند شد.
اطلاعات contextيي که در سطح رویداد ارسال می شوند، نسبت به اطلاعات contextيي که در زمان راه اندازی SDK تنظیم شده اند، اولویت دارند.

استفاده از متد putCustomContext (Using putCustomContext method)

شما می توانید از متد putCustomContext بر روی یک نمونه از RudderOption استفاده کنید تا اطلاعات context سفارشي را به عنوان یک موجوديت تو در تو ¹³در context به هنگام ارسال رویدادها تنظیم نمایید.

نمونه ای از تعیین context سفارشي با استفاده از یک نمونه RudderOption و ارسال آن در فراخوانی track:

SDK اطلاعات contextيي که توسط متد putCustomContext تعیین شده اند را برای رویدادهای بعدی حفظ نمی کند. بنابراین، لازم است این متد را در هر بار که می خواهید context سفارشي را برای رویدادی تنظیم کنید، به کار ببرید.

تنظيم شناسه تبليغاتي (Setting the advertisement ID)
به طور پیش فرض، زبلاين، شناسه تبلیغاتی يا advertisement ID را تنها در صورت برآورده شدن سه شرط زیر گردآوری می کند:

اگر withAutoCollectAdvertId در هنگام راه اندازي اوليه SDK به true تنظیم شده باشد.

اگر com.google.android.gms.ads.identifier.AdvertisingIdClient در مسیر کلاس برنامه شما موجود باشد.
اگرگزینه limitAdTracking بر روی دستگاه شما غیرفعال باشد.

در اين صورت، شما می توانید با استفاده از متد putAdvertisingId، شناسه تبلیغاتی يا advertisement ID را تنظیم نمایید.

متد putAdvertisingId یک متد static است و می توان آن را قبل یا بعد از راه اندازي اوليه SDK، فراخوانی کرد.

اگر withAutoCollectAdvertId روی true تنظیم شده باشد و شما مقدار شناسه تبلیغاتی يا advertisement ID را با استفاده از متد putAdvertisingId تنظیم کنید، Zebline به جای گردآوري خودکار، از مقدار ارائه شده توسط کاربر استفاده می کند.

پس از بازنشانی يا reset شناسه تبلیغاتی با استفاده از متد clearAdvertisingId، Zebline دوباره شروع به گردآوري خودکار شناسه تبلیغاتی می کند.

جهت حذف شناسه تبلیغاتی، از متد clearAdvertisingId استفاده کنید:

متد clearAdvertisingId یک متد static نیست و بنابراین تنها پس از راه اندازي اوليه SDK قابل فراخوانی است.

Zebline، gaid را در context.device.advertisementId تنظیم می کند.

فیلتر کردن رویدادها (Filtering events)
هنگام ارسال رویدادها به یک مقصد از طریق device mode، می توانید صراحتاً مشخص کنید که کدام رویدادها باید حذف شوند یا اجازه عبور داده شوند - با استفاده از لیست سفید¹⁴ یا لیست سیاه¹⁵.
رديابي session هاي کاربر (Tracking user sessions)
به طور پیش فرض، SDK اندروید به طور خودکار sessionهاي کاربر را ردیابی می کند. این بدان معناست که Zebline به طور خودکار شروع و پایان یک session کاربری را بر اساس مدت زمان عدم فعالیت تعیین شده در SDK (که به طور پیش فرض ۵ دقیقه است) مشخص می کند.
نکته: جهت ردیابی خودکار session ها در SDK اندروید، باید گزینه withTrackLifecycleEvents نیز بر روی true تنظیم شود. دلیل این امر آن است که Zebline رویدادهای باز شدن برنامه¹⁶، نصب شدن برنامه¹⁷، یا به روزرسانی برنامه¹⁸ را به عنوان آغاز یک session جدید در نظر می گیرد.

برای غیرفعال کردن ردیابی خودکار session، پارامتر withAutoSessionTracking را بر روی false تنظیم کنید.

دريافت شناسه session (Getting the session ID)

برای بازیابی sessionId مربوط به یک session، از متد getSessionId() استفاده کنید.

getSessionId() از نسخه v1.19.0 به بعد در SDK اندروید موجود است.

ردیابی رویدادهای چرخه عمر (Tracking lifecycle events)
به طور پیش فرض، زبلاين رویدادهای اختیاری چرخه عمر برنامه¹⁹ زیر را ردیابی می کند:

نصب برنامه²⁰
به روزرسانی برنامه²¹
باز شدن برنامه²²
پس زمینه شدن برنامه²³

برای غیرفعال کردن ردیابی این رویدادها، متد withTrackLifecycleEvents را هنگام راه اندازي اوليه SDK بر روی false تنظیم کنید. با این حال، توصیه می شود که آنها را فعال نگه دارید.

ردیابی رویدادها با AndroidX LifecycleObserver

از نسخه 1.14.0 به بعد، SDK اندروید از یک روش جدید و کارآمدتر برای ردیابی رویدادهای چرخه عمر برنامه شما با استفاده از کلاس AndroidX LifecycleObserver پشتیبانی می کند، که در مقابل روش استاندارد ردیابی رویدادهای چرخه عمر (با استفاده از ActivityLifecycleCallbacks) قرار دارد.

برای ردیابی رویدادهای چرخه عمر با این روش، وابستگی های زیر را به برنامه خود اضافه کنید:

توجه داشته باشید که این روش به طور پیش فرض غیرفعال يا disabled است. withNewLifecycleEvents را هنگام راه اندازي اوليه SDK اندروید بر روی true تنظیم کنید تا از این روش بتوانيد استفاده کنید:

اگر withNewLifecycleEvents بر روی true تنظیم شده باشد اما وابستگی های مورد نیاز در برنامه شما موجود نباشند، در اين صورت، SDK اندروید به روش پیش فرض با استفاده از withTrackLifeCycleEvents (اگر هنگام راه اندازي اوليه SDK بر روی true تنظیم شده باشد) برای ردیابی رویدادهای چرخه عمر بازخواهد گشت.

جدول زیر جزئیات ماتریس ردیابی رویدادهای چرخه عمر را نشان می دهد:

New way of tracking lifecycle events(withNewLifecycleEvents)	Standard way of tracking lifecycle events(withTrackLifecycleEvents)	Presence of AndroidX LifecycleObserver dependencies in app	Resultant way
Enabled	Enabled	Yes	جدید
Enabled	Enabled	No	استاندارد
Enabled	Disabled	No	رویدادهای چرخه عمر ردیابی نمی شوند.
Enabled	Disabled	Yes	جدید
Disabled	Enabled	NA	استاندارد
Disabled	Disabled	NA	رویدادهای چرخه عمر ردیابی نمی شوند.

ردیابی deep links (Tracking deep links)
از نسخه 1.14.0 به بعد، اگر هر برنامه ای را از طریق deep link باز کنید، SDK اندروید، رویداد Deep Link Opened را با تمام جزئیات مرتبط با deep link به عنوان ویژگی های آن ارسال می کند. در نسخه های قبلی، SDK این جزئیات را به عنوان بخشی از ویژگی های رویداد Application Opened درنظر می گرفت.
این ویژگی به طور پیش فرض فعال يا enabled است. برای غیرفعال کردن آن، withTrackDeepLinks را به هنگام راه اندازي اوليه SDK بر روی false تنظیم کنید - این کار باعث می شود، SDK تمام رویدادهای اضافی Deep Link Opened را حذف کند.
عيب یابي(Debugging)
اگر با هرگونه مشکلی در مورد SDK اندروید Zebline مواجه شدید، می توانید ورودی VERBOSE یا DEBUG را برای پیدا کردن مشکل فعال کنید. برای فعال کردن ورودی، راه اندازي اوليه RudderClient خود را به شکل زیر تغییر دهید:

کرومکست (Chromecast)
Google Chromecast یک دستگاه ²⁴است که به پورت HDMI تلویزیون یا مانیتور شما متصل می شود و می تواند برای پخش محتوا از تلفن یا کامپیوتر شما استفاده شود.
Zebline از ادغام SDK اندروید با برنامه Cast شما پشتیبانی می کند.

سوالات متداول (FAQ)
چه نسخه ای از اندروید برای نصب SDK اندروید Zebline لازم است؟
ما در حال حاضر API 14: اندروید 4.0 (IceCreamSandwich) یا بالاتر را پشتیبانی می کنیم.
کلاس Application برای راه اندازي کلاينت Zebline وجود ندارد. چه کاری انجام دهم؟
راهنمای ما در مورد چگونگی افزودن یک کلاس Application به برنامه اندروید خود را دنبال کنید.
چگونه مجوزهای اندروید را تنظیم کنم؟
بخش تنظیم مجوزهای اندروید بالا را برای انجام این کار ببینید.
چگونه SDK اندروید را در برنامه هایی با minSDKVersion کمتر از 20 استفاده کنم؟
به طور پیش فرض، SDK اندروید از برنامه هایی با minSDKVersion کمتر از 20 پشتیبانی نمی کند. می توانید این پشتیبانی را با دنبال کردن مراحل زیر اضافه کنید:

وابستگی زیر را به فایل build.gradle برنامه خود اضافه کنید:

تابع tlsBackport() را در MainActivity خود به شکل نشان داده شده اضافه کنید:

در نهایت، تابع tlsBackport() را در ابتدای متد onCreate() خود در MainActivity فراخوانی کنید.

آیا می توانم از کتابخانه با Maven استفاده کنم؟

بله، می توانید از کتابخانه با maven استفاده کنید.

چگونه بررسی کنم که آیا یک رویداد خاص در حال اجرا است یا خیر؟

با استفاده از دستور زیر در ابزار Logcat پس از تنظیم logLevel به VERBOSE.

چگونه ویژگی های کاربر(user traits) را پس از انجام فراخواني identify دریافت کنم؟

می توانید ویژگی های کاربر را پس از انجام فراخواني identify به شکل نشان داده شده در قطعه کد زیر دریافت کنید:

آیا می توانم ردیابی رویداد را تا زمانی که کاربر رضایت خود را اعلام کند، غیرفعال کنم؟

بله، می توانید. Zebline به شما امکان می دهد تا با استفاده ازAPI optOut، ردیابی هر فعالیت کاربری را تا زمانی که کاربر رضایت خود را اعلام کند، غیرفعال کنید. این در مواردی که برنامه شما وابسته به مخاطب است (مثلاً افراد زیر سن قانونی) یا زمانی که از برنامه برای ردیابی رویدادهای کاربر استفاده میکنید (مثلاً کاربران اتحادیه اروپا) برای رعایت مقررات حفاظت از داده ها و حریم خصوصی لازم است. API optOut مقدار true یا false را به عنوان یک مقدار بولین برای فعال یا غیرفعال کردن ردیابی فعالیت های کاربر درنظر می گیرد. بنابراین، برای غیرفعال کردن ردیابی کاربر، می توانید از API optOut به شکل نشان داده شده استفاده کنید:

پس از اعلام رضایت کاربر، می توانید دوباره ردیابی کاربر را فعال کنید:

برای اطلاعات بیشتر در مورد API optOut، به بخش فعال/غیرفعال کردن ردیابی کاربر از طریق API optOut بالا مراجعه کنید.

شما تنها نیاز دارید که یک بار API optOut را با پارامتر مورد نیاز فراخوانی کنید، زیرا اطلاعات حتی اگر دستگاه خود را راه اندازی مجدد کنید، در داخل دستگاه باقی می ماند.

چگونه SDK با خطاهای مختلف کلاينت/ سرور برخورد می کند؟

در صورت خطاهای کلاينت، به عنوان مثال اگر کلید نوشتن منبع ارائه شده به SDK نادرست باشد، Zebline به شما پاسخ 400 Bad Request می دهد و عملیات را فوراً متوقف می کند.

برای انواع دیگر خطاهای شبکه (به عنوان مثال URL Data Plane نامعتبر)، SDK سعی می کند رویدادها را به صورت تدریجی به Zebline ارسال کند (هر 1 ثانیه، 2 ثانیه، 3 ثانیه و غیره).

آیا می توانم رمزگذاری را تنها بر روی پایگاه های داده جدید اعمال کنم؟

رمزگذاری پایگاه داده بر روی پایگاه های داده جدید و موجود کار می کند. شیء DbEncryption را در RudderConfig.Builder() هنگام راه اندازي اوليه SDK اندروید قرار دهید.

آیا می توانم رمزگذاری را تنها بر روی پایگاه های داده جدید اعمال کنم؟

رمزگذاری پایگاه داده هم بر روی پایگاه های داده جدید و هم موجود کار می کند. شیء DbEncryption را در RudderConfig.Builder() هنگام راه اندازي SDK اندروید قرار دهید.

شما می توانید از این شیء برای تبدیل یک پایگاه داده غیررمزگذاری شده به یک پایگاه داده رمزگذاری شده و برعکس استفاده کنید.

آیا میتوانم رمزگذاری را از یک پایگاه داده رمزگذاری شده حذف کنم؟

بله، می توانید.

اگر پایگاه داده قبلاً رمزگذاری شده باشد، می توانید پایگاه داده را به روش زیر رمزگشایی کنید:

مطمئن شوید که وابستگی android-database-sqlcipher را در فایل build.gradle سطح ماژول خود تنظیم کرده اید.

برای اطلاعات بیشتر، به DbEncryption مراجعه کنید.

اگر کلید رمزگذاری ارائه شده با کلیدی که پایگاه داده با آن رمزگذاری شده است متفاوت باشد چه اتفاقی می افتد؟

پس از رمزگذاری پایگاه داده:

اگر هیچ کلیدی(no key) ارائه نشود، SDK پایگاه داده فعلی با رویدادهای ارسال نشده را حذف کرده و به جای آن یک پایگاه داده جدید غیررمزگذاری شده ایجاد می کند.
اگر یک کلید اشتباه(wrong key) ارائه شود، SDK پایگاه داده فعلی با رویدادهای ارسال نشده را حذف کرده و یک پایگاه داده رمزگذاری شده جدید با کلید داده شده ایجاد می کند.

SDK اندروید چگونه با رویدادهایی که بزرگتر از 32 KB هستند برخورد می کند؟

SDK اندروید هر رویدادی که بزرگتر از 32KB باشد را حذف می کند.

SDK اندرويد

SDK اندرويد(Android SDK)

الزامات راه اندازي SDK(SDK setup requirements)​

نصب SDK(Installing the SDK)​

تنظیم مجوزهای اندروید (Setting Android permissions)​

قوانين Android ProGuard (Android ProGuard rules)​

راه اندازي کلاينت زبلاين (Initializing the Zebline client)​

پيکربندي کلاينت زبلاين(Configuring your Zebline client)​

رمزنگاري پايگاه داده (DbEncryption)​

درخواست هاي Gzipping (Gzipping requests)​

شناسایی (Identify)​

مقداردهي مجدد شناسه ناشناس (Overriding anonymous ID)​

غيرفعال سازي مجموعه شناسه دستگاه (Disabling device ID collection)​

چگونگی تنظیم شناسه ناشناس توسط SDK (How SDK sets anonymous ID)​

تنظيم شناسه سفارشي (Setting a custom ID)​

رديابي (Track)​

صفحه نمايش (Screen)​

گروه (Group)​

نام مستعار (Alias)​

بازنشاني (Reset)​

تنظيماتGDPR (Consent-driven user tracking/GDPR support)​

تنظيم توکن دستگاه اندرويد (Setting the Android device token)​

تنظيم context سفارشي (Setting custom context)​

هنگام راه اندازی اولیه SDK (During SDK initialization)​

استفاده از متد putCustomContext (Using putCustomContext method)​

تنظيم شناسه تبليغاتي (Setting the advertisement ID)​

فیلتر کردن رویدادها (Filtering events)​

رديابي session هاي کاربر (Tracking user sessions)​

دريافت شناسه session (Getting the session ID)​

ردیابی رویدادهای چرخه عمر (Tracking lifecycle events)​

ردیابی deep links (Tracking deep links)​

عيب یابي(Debugging)​

کرومکست (Chromecast)​

سوالات متداول (FAQ)​

الزامات راه اندازي SDK(SDK setup requirements)

نصب SDK(Installing the SDK)

تنظیم مجوزهای اندروید (Setting Android permissions)

قوانين Android ProGuard (Android ProGuard rules)

راه اندازي کلاينت زبلاين (Initializing the Zebline client)

پيکربندي کلاينت زبلاين(Configuring your Zebline client)

رمزنگاري پايگاه داده (DbEncryption)

درخواست هاي Gzipping (Gzipping requests)

شناسایی (Identify)

مقداردهي مجدد شناسه ناشناس (Overriding anonymous ID)

غيرفعال سازي مجموعه شناسه دستگاه (Disabling device ID collection)

چگونگی تنظیم شناسه ناشناس توسط SDK (How SDK sets anonymous ID)

تنظيم شناسه سفارشي (Setting a custom ID)

رديابي (Track)

صفحه نمايش (Screen)

گروه (Group)

نام مستعار (Alias)

بازنشاني (Reset)

تنظيماتGDPR (Consent-driven user tracking/GDPR support)

تنظيم توکن دستگاه اندرويد (Setting the Android device token)

تنظيم context سفارشي (Setting custom context)

هنگام راه اندازی اولیه SDK (During SDK initialization)

استفاده از متد putCustomContext (Using putCustomContext method)

تنظيم شناسه تبليغاتي (Setting the advertisement ID)

فیلتر کردن رویدادها (Filtering events)

رديابي session هاي کاربر (Tracking user sessions)

دريافت شناسه session (Getting the session ID)

ردیابی رویدادهای چرخه عمر (Tracking lifecycle events)

ردیابی deep links (Tracking deep links)

عيب یابي(Debugging)

کرومکست (Chromecast)

سوالات متداول (FAQ)