SDK فلاتر

SDK فلاتر (flutter SDK)

مقدمه

اين سند حاوي اطلاعاتي جامع جهت نصب و استفاده از Flutter SDK سرويس مارکتينگ اتوماسيون Zebline است.

از Zebline Flutter SDK برای ارسال رویدادها از اپلیکیشن‌های Flutter خود به به سرويس زبلاين استفاده کنید.

Zebline Flutter SDK این امکان را فراهم می‌کند تا رویدادهایی که در اپلیکیشن شما رخ می‌دهند، رهگیری (track) و به سرويس زبلاين ارسال شوند.

برای آشنایی بیشتر با نحوه‌ی استفاده و قابلیت‌های این SDK، به راهنماهای زیر مراجعه کنید:

راهنما	توضیحات
نصب SDK	نحوه‌ی نصب و راه‌اندازی Zebline Flutter SDK
APIهای پشتیبانی‌شده	لیستی از APIهایی که برای ارسال اطلاعات رویداد قابل استفاده هستند
قابلیت‌ها و کاربردها	ویژگی‌ها و موارد استفاده‌ی SDK در زمینه‌های مختلف مانند رهگیری رویداد، فیلتر کردن، اشکال‌زدایی و غیره

Flutter SDK Installation

در این بخش، مراحل نصب و راه‌اندازی Zebline Flutter SDK به‌صورت کامل شرح داده شده است.

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

برای راه‌اندازی Zebline Flutter SDK، باید شرایط زیر فراهم باشد:

ابتدا باید یک حساب کاربری در Zebline بسازید.
پس از ثبت‌نام، در بخش Integration → Setup یک منبع (source) Flutter تعریف کنید. پس از انجام این کار، یک Write Key برای این منبع به شما نمایش داده می‌شود (مطابق تصویر زیر):

علاوه بر آن، به دو آدرس URL نیاز دارید:
- آدرس داده‌ها (Data Plane URL)
- آدرس کنترل (Control Plane URL)

در تب Setup داشبورد Zebline، یک قطعه کد برای نصب SDK قرار داده شده که شامل Write Key، آدرس داده‌ها و آدرس کنترل است. شما می‌توانید از این اطلاعات برای یکپارچه‌سازی SDK در پروژه‌ی خود استفاده کنید.

DATA PLANE URL : https://analytics.zebline.com
CONTROL PLANE URL : https://c.zebline.com

نصب SDK(Installing the SDK)

برای افزودن SDK به پروژه‌ی خود از طریق Pub، مراحل زیر را دنبال کنید:

اضافه کردن به pubspec.yaml

در فایل pubspec.yaml، کتابخانه‌ی rudder_sdk_flutter را به بخش dependencies اضافه کنید:

dependencies:

rudder_sdk_flutter: ^2.0.1

نصب وابستگی‌ها

به دایرکتوری اصلی پروژه‌ی خود بروید و دستور زیر را برای نصب تمام وابستگی‌ها اجرا کنید:

flutter pub get

مقداردهی اولیه (Initialization) SDK

Importپکیج‌ها

کد زیر را در فایل اصلی اپلیکیشن خود اضافه کنید:

import 'package:rudder_sdk_flutter_platform_interface/platform.dart';

import 'package:rudder_sdk_flutter/RudderController.dart';

مقداردهی و پیکربندی SDK

کد زیر را برای مقداردهی اولیه‌ی SDK در برنامه خود قرار دهید:

final RudderController rudderClient = RudderController.instance;

RudderLogger.init(RudderLogger.VERBOSE);

RudderConfigBuilder builder = RudderConfigBuilder();

builder.withDataPlaneUrl(&lt;DATA_PLANE_URL&gt;);

builder.withControlPlaneUrl(CONTROL_PLANE_URL)

builder.withTrackLifecycleEvents(true);

rudderClient.initialize(&lt;WRITE_KEY&gt;,config: builder.build());

🔁 نکته: مقادیر زیر را با داده‌های واقعی خود جایگزین کنید:

<WRITE_KEY>
<DATA_PLANE_URL>
<CONTROL_PLANE_URL>

متد initialize دارای پارامترهای زیر است:

گزینه‌های پیکربندی اولیه SDK

شما می‌توانید رفتار SDK را با استفاده از شیء RudderConfig که در متد rudderClient.initialize() ارسال می‌شود، پیکربندی کنید.

دو روش برای ساخت شیء RudderConfig وجود دارد:

استفاده مستقیم از سازنده‌ی RudderConfig با پارامترهای موردنظر
استفاده از APIهای کلاس RudderConfigBuilder برای تنظیم گام‌به‌گام

RudderConfig constructor parameter	RudderConfigBuilder class API	Type	Description	Default value
dataPlaneUrl	withDataPlaneUrl()	String	The data plane URL.	https://analytics.zebline.com
flushQueueSize	withFlushQueueSize()	int	Number of events in a batch request to the server.	30
isDebug	withDebug()	bool	When enabled, sets the log level as debug. For more information, refer to the Debugging section.	false
logLevel	withLogLevel()	int	Controls the logs you want to see from the Flutter SDK.	RudderLogger.RudderLogLevel.NONE
mobileConfig	withMobileConfig()	MobileConfig	Refer to the mobileConfig parameters section below.	-
webConfig	withWebConfig()	WebConfig	Refer to the webConfig parameters section below.	-
controlPlaneUrl	withControlPlaneUrl()	String	This parameter should be changed only if you are self-hosting the control plane. The SDK will add /sourceConfig along with this URL to fetch the configuration.	https://c.zebline.com
dataPlaneUrl	withDataPlaneUrl()	String	The data plane URL.	https://analytics.zebline.com
flushQueueSize	withFlushQueueSize()	int	Number of events in a batch request to the server.	30
isDebug	withDebug()	bool	When enabled, sets the log level as debug. For more information, refer to the Debugging section.	false
logLevel	withLogLevel()	int	Controls the logs you want to see from the Flutter SDK.	RudderLogger.RudderLogLevel.NONE
mobileConfig	withMobileConfig()	MobileConfig	Refer to the mobileConfig parameters section below.	-
webConfig	withWebConfig()	WebConfig	Refer to the webConfig parameters section below.	-
controlPlaneUrl	withControlPlaneUrl()	String	This parameter should be changed only if you are self-hosting the control plane. The SDK will add /sourceConfig along with this URL to fetch the configuration.	https://c.zebline.com
dataPlaneUrl	withDataPlaneUrl()	String	The data plane URL.	https://analytics.zebline.com
flushQueueSize	withFlushQueueSize()	int	Number of events in a batch request to the server.	30

پارامترهای mobileConfig

شیء mobileConfig شامل تنظیمات اختصاصی مربوط به SDK در پلتفرم موبایل است:

Parameter	Type	Description	Default value
dbCountThreshold	int	Number of events to be saved in the SQLite database. Once this limit is reached, the older events are deleted from the database.	10000
sleepTimeOut	int	Minimum waiting time to flush the events to the server.	10 seconds
configRefreshInterval	int	Fetches the config from the dashboard after this specified time.	2
trackLifecycleEvents	bool	Determines if the SDK will capture application life cycle events automatically.	true
autoCollectAdvertId	bool	Determines if the SDK will collect the advertisement ID.	false
recordScreenViews	bool	When enabled, the SDK automatically records the screens viewed by the user.	false
dbEncryption	RudderDBEncryption	Specify whether to encrypt/decrypt the database using the specified key.	-

پارامترهای webConfig

شیء webConfig شامل پارامترهای پیکربندی مربوط به استفاده از SDK در برنامه‌های Flutter Web است.

نکات مهم:

شیء webConfig در SDK فلاتر از تمامی گزینه‌های بارگذاری (load options) که در SDK جاوااسکریپت پشتیبانی می‌شوند، به‌جز موارد زیر پشتیبانی می‌کند:
- logLevel
- integrations
- configUrl
- getSourceConfig

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

آیا باید چیزی به فایل ProGuard اندروید اضافه کنم؟

اگر در حال استفاده از حالت کامل بهینه‌سازی ProGuard هستید، خطوط زیر را برای جلوگیری از حذف کدهای ضروری و پشتیبانی صحیح SDK، به فایل ProGuard پروژه‌ی اندرویدی خود اضافه کنید:

// Reporter Module

keep class com.rudderstack.android.ruddermetricsreporterandroid.models.LabelEntity { \*; }

keep class com.rudderstack.android.ruddermetricsreporterandroid.models.MetricEntity { \*; }

keep class com.rudderstack.android.ruddermetricsreporterandroid.models.ErrorEntity { \*; }

// Required for the usage off TypeToken class in Utils.converToMap, Utils.convertToList

keep class com.google.gson.reflect.TypeToken { \*; }

keep class \* extends com.google.gson.reflect.TypeToken

// Required for the serialization of SourceConfig once it is downloaded.

keep class com.google.gson.internal.LinkedTreeMap { \*; }

keep class \* implements java.io.Serializable { \*; }

keep class com.rudderstack.rudderjsonadapter.RudderTypeAdapter { \*; }

keep class \* extends com.rudderstack.rudderjsonadapter.RudderTypeAdapter

// Required to ensure the DefaultPersistenceProviderFactory is not removed by Proguard

// and works as expected even when the customer is not using encryption feature.

dontwarn net.sqlcipher.Cursor

dontwarn net.sqlcipher.database.SQLiteDatabase$CursorFactory

dontwarn net.sqlcipher.database.SQLiteDatabase

dontwarn net.sqlcipher.database.SQLiteOpenHelper

keep class com.rudderstack.android.sdk.core.persistence.DefaultPersistenceProviderFactory { \*; }

// Required for the usage of annotations across reporter and web modules

dontwarn com.fasterxml.jackson.annotation.JsonIgnore

dontwarn com.squareup.moshi.Json

dontwarn com.fasterxml.jackson.annotation.JsonProperty

// Required for Device Mode Transformations

keep class com.rudderstack.android.sdk.core.TransformationResponse { \*; }

keep class com.rudderstack.android.sdk.core.TransformationResponseDeserializer { \*; }

keep class com.rudderstack.android.sdk.core.TransformationRequest { \*; }

Flutter SDK API

Zebline Flutter SDK یک مجموعه API جامع در اختیار شما قرار می‌دهد تا بتوانید داده‌های مربوط به رویدادهای کاربران را به به سرويس زبلاين ارسال و رهگیری کنید.

شناسایی (Identify)

متد identify به شما این امکان را می‌دهد که یک کاربر را شناسایی کرده و ویژگی‌های (traits) او مانند نام، آدرس ایمیل، شماره تلفن و ... را ذخیره و با رفتار او مرتبط کنید.

یک نمونه رویداد identify به شرح زیر است:

RudderTraits traits = RudderTraits();

traits.putBirthdayDate(new DateTime.now());

traits.putEmail("<alex@example.com>");

traits.putFirstName("Alex");

traits.putLastName("Keener");

traits.putGender("Male");

traits.putPhone("5555555555");

Address address = Address();

address.putCity("City");

address.putCountry("USA");

traits.putAddress(address);

traits.put("boolean", true);

traits.put("integer", 50);

traits.put("float", 120.4);

traits.put("long", 1234);

traits.put("string", "hello");

traits.put("date", new DateTime.now().millisecondsSinceEpoch);

rudderClient.identify("1hKOmRA4GRlm", traits: traits, options: null);

| **Name** | **Data Type** | **Description** | | --- | --- | --- | | userId Required | String | Unique identifier for a user in your database. | | traits | RudderTraits | An optional dictionary of the user’s traits like name or email. | | options | RudderOption | Extra options for the identify event. |

✅ پس از شناسایی کاربر، SDK اطلاعات او را ذخیره کرده و در فراخوانی‌های بعدی track یا screen نیز استفاده می‌کند.

🔐 نکات مهم درباره anonymousId و شناسایی دستگاه

در نسخه‌های قدیمی‌تر از ۲.۵.۰، SDK شناسه دستگاه (device ID) را به عنوان anonymousId استفاده می‌کند.
از نسخه ۲.۵.۰ به بعد، SDK از یک UUID تصادفی به عنوان anonymousId استفاده می‌کند.

تنظیم شناسه ناشناس(Setting a custom anonymous Id)

شما می توانید از متد زیر برای استفاده از anonymousId خودتان با SDK استفاده کنید.

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

rudderClient.putAnonymousId(&lt;ANONYMOUS_ID&gt;);

نحوه‌ی تعیین شناسه دستگاه (deviceId) در اندروید و iOS :

در دستگاه‌های اندرویدی:
شناسه دستگاه یا deviceId در اولین بوت (راه‌اندازی) سیستم تعیین می‌شود. این شناسه در بین اپلیکیشن‌ها و نصب‌های مختلف ثابت می‌ماند و فقط پس از انجام (factory reset) تغییر می‌کند.

در سیستم‌عامل iOS(طبق مستندات اپل):
چندین اپلیکیشن که از سوی یک فروشنده منتشر شده‌اند، یک deviceId مشترک دریافت می‌کنند. اگر تمام اپلیکیشن‌های مربوط به آن فروشنده حذف و سپس مجدداً نصب شوند، یک deviceId جدید اختصاص داده می‌شود.

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

از نسخه‌ی 2.5.0 به بعد، می‌توانید با تنظیم مقدار collectDeviceId در شیء MobileConfig روی false، جمع‌آوری شناسه دستگاه را غیرفعال کنید.

تغییراتی که هنگام تنظیم این گزینه روی false رخ می‌دهد:

SDK مقدار context.device.id را به عنوان بخشی از داده‌های رویداد (event payload) ارسال نمی‌کند.
اگر مقدار anonymousId برابر با شناسه دستگاه باشد، SDK آن را با یک شناسه UUID تصادفی جایگزین می‌کند.

این تغییرات برای هماهنگی بیشتر SDK با سیاست‌های مربوط به جمع‌آوری شناسه دستگاه اعمال شده‌اند.

نمونه کد تنظیم غیرفعال‌سازی جمع‌آوری شناسه دستگاه:

MobileConfig mc = MobileConfig(collectDeviceId: false);

RudderConfigBuilder builder = RudderConfigBuilder();

builder

..withMobileConfig(mc)

..withDataPlaneUrl('DATA_PLANE_URL')

..withControlPlaneUrl(CONTROL_PLANE_URL)

..withDataResidencyServer(DataResidencyServer.US);

rudderClient.initialize('WRITE_KEY', config: builder.build(), options: null);

نکات مهم هنگام ارتقا به نسخه جدید SDK (از نسخه‌های قبل از 2.5.0) و غیرفعال‌کردن جمع‌آوری شناسه دستگاه:

اطمینان حاصل کنید که تبدیل‌ها (transformations) یا منطق‌های وابسته به context.device.id در سیستم شما دیگر به این مقدار وابسته نیستند؛ زیرا SDK دیگر آن را ارسال نمی‌کند.

ستون context.device.id در data warehouse شما از این به بعد مقدار جدیدی دریافت نخواهد کرد، اما همچنان داده‌های قبلی که توسط نسخه‌های پیشین SDK ارسال شده‌اند در آن موجود خواهند بود.

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

برای نصب مستقیم/جدید^[1] SDK:

Zebline به‌صورت پیش‌فرض از UUID به عنوان مقدار anonymousId استفاده می‌کند، بدون توجه به این‌که مقدار collectDeviceId روی true یا false تنظیم شده باشد.

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

اگر Flutter SDKخود را از نسخه‌ای قدیمی‌تر (قبل از نسخه 2.5.0) به‌روزرسانی می‌کنید، رفتار SDK به صورت زیر خواهد بود:

Zebline همچنان از شناسه دستگاه (device ID) به عنوان anonymousId استفاده می‌کند و رفتار قبلی حفظ می‌شود، مگر اینکه مقدار collectDeviceId را روی false تنظیم کنید.
اگر collectDeviceId را روی false قرار دهید، SDK بررسی می‌کند که آیا مقدار فعلی anonymousId برابر با شناسه دستگاه است یا خیر. اگر چنین باشد، مقدار anonymousId را به یک UUID جدید تغییر می‌دهد.
اگر قبلاً با استفاده از متد putAnonymousId، یک anonymousId سفارشی تعیین کرده باشید، SDK در هیچ شرایطی (حتی با تنظیم collectDeviceId: false) آن مقدار را تغییر نمی‌دهد.

دریافت ویژگی‌های کاربر (Obtaining user traits)

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

Map context = await rudderClient.getRudderContext();

print(context\["traits"\]);

در برنامه‌های وب نیز getRudderContext اطلاعات traits و anonymousId را برمی‌گرداند.

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

شما می توانید یک شناسه سفارشی را همراه با userId استاندارد در فراخوان های identify خود ارسال کنید. زبلاين این مقدار را در context.externalId اضافه می کند.

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

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

RudderOption option = RudderOption();

option.putExternalId("externalId", "some_external_id_1");

rudderClient.identify("1hKOmRA4GRlm", options: option);

رديابي (Track)

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

یک نمونه رویداد track به شرح زیر است:

RudderProperty property = RudderProperty();

property.put("test_key_1", "test_key_1");

RudderProperty childProperty = RudderProperty();

childProperty.put("test_child_key_1", "test_child_value_1");

property.put("test_key_2",childProperty);

rudderClient.track("Test Event", properties: property);

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

Name	Type	Description
Name Required	String	Name of the tracked event.
properties	RudderProperty	An optional dictionary of the properties associated with the event.
options	RudderOption	Extra options for the track event.

### رویدادهای چرخه‌ی حیات اپلیکیشن (Lifecycle Events)

Zebline Flutter SDK به‌طور خودکار رویدادهای زیر را رهگیری می‌کند:

نصب اپلیکیشن (Application Installed)
بروزرسانی اپلیکیشن (Application Updated)
باز شدن اپلیکیشن (Application Opened)
قرار گرفتن اپلیکیشن در پس‌زمینه (Application Backgrounded)

در صورتی که تمایلی به رهگیری این رویدادها ندارید، می‌توانید هنگام پیکربندی SDK، متد زیر را فراخوانی کنید:

builder.withTrackLifeCycleEvents(false);

✅ توصیه می‌شود این رویدادها را غیرفعال نکنید مگر در موارد خاص، چون برای تحلیل رفتار کاربران مفید هستند.

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

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

یک نمونه از رویداد screen به شرح زیر است:

RudderProperty screenProperty = RudderProperty();

screenProperty.put("browser", "Chrome");

screenProperty.put("device", "Macbook Pro");

rudderClient.screen("Walmart Cart",

category: "home",

properties: screenProperty,

options: null);

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

Name	Type	Description
screenName Required	String	Name of the viewed screen.
category	String	Category of the viewed page (web) or screen (mobile).
properties	RudderProperty	An optional dictionary of the properties associated with the event.
options	RudderOption	Extra options for the screen event.

### ثبت خودکار صفحه نمایش (Automatic screen recording)

پارامتر recordScreenViews فقط نمایش صفحات در activityهای اندروید و view controllerهای iOS را رهگیری می‌کند؛ اما صفحات خود Flutter را شامل نمی‌شود.

برای رهگیری دستی صفحات در اپلیکیشن‌های Flutter، مراحل زیر را دنبال کنید:

مسیرها (Routes) را به همراه نام‌های آن‌ها در سازنده‌ی MaterialApp در ویجت ورودی (Entry Widget) تعریف کنید.
یک نمونه از custom navigation observer را ساخته و در همان سازنده‌ی MaterialApp ثبت کنید.
کد زیر شامل پیاده‌سازی این دو مرحله است:

 import 'package:flutter/material.dart'; 

 import 'home_screen.dart';

import 'screen2.dart';

import 'screen3.dart'; 

 import 'my_route_observer.dart'; 

class MyApp extends StatelessWidget {

const MyApp({Key? key}) : super(key: key);

@override

Widget build(BuildContext context) {

return MaterialApp(

theme: ThemeData(

primarySwatch: Colors.blue,

),

// Step 2. Registering an instance of our custom navigation observer.

navigatorObservers: [

MyRouteObserver(),

],

home: const HomeScreen(),

// Step 1. Defining the named routes

routes: {

'screen2': (context) => const Screen2(),

'screen3': (context) => const Screen3(),

},

);

}

}

Future&lt;void&gt; main() async {

runApp(const MyApp());

}

در نهایت، قطعه‌کدی که مربوط به تعریف custom navigation observer است را به پروژه اضافه کنید.

import 'package:flutter/material.dart'; 

 import 'package:rudder_sdk_flutter/RudderController.dart'; 

class MyRouteObserver extends RouteObserver&lt;PageRoute<dynamic&gt;> {

@override

void didPush(Route&lt;dynamic&gt; route, Route&lt;dynamic&gt;? previousRoute) {

super.didPush(route, previousRoute);

if (route is PageRoute && route.settings.name != null) {

RudderController.instance.screen(route.settings.name!);

}

}

@override

void didPop(Route&lt;dynamic&gt; route, Route&lt;dynamic&gt;? previousRoute) {

super.didPop(route, previousRoute);

if (previousRoute is PageRoute && route is PageRoute) {

RudderController.instance.screen(previousRoute.settings.name!);

}

}

}

گروه (Group)

فراخوانی group، کاربر را به یک سازمان خاص مرتبط می کند. همچنین می‌توانید ویژگی‌های مرتبط با آن گروه را ثبت کنید. نمونه ای از فراخوانی group برای API در زیر آمده است:

RudderTraits groupTraits = RudderTraits();

groupTraits.put("foo", "bar");

groupTraits.put("foo1", "bar1");

rudderClient.group("sample_group_id",

groupTraits: groupTraits, options: null);

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

Name	Type	Description
groupId Required	String	Unique identifier of the group in your database.
groupTraits	RudderTraits	An optional dictionary of the group’s traits like name or email.
options	RudderOption	Extra options for the group event.

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

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

rudderClient.alias("new_user_id", options: null);

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

Name	Type	Description
newId Required	String	The new user identifier.
options	RudderOption	Extra options for the alias event.

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

بازنشاني Reset

شما می‌توانید از متد reset برای حذف ویژگی‌های ذخیره‌شده‌ی کاربر استفاده نمایید. برای حذف اطلاعات ذخیره‌شده‌ی کاربر، می‌توانید از متد reset() استفاده کنید. اگر بخواهید anonymousId را نیز ریست کنید، از پارامتر clearAnonymousId: true استفاده نمایید.

یک نمونه فراخوانی reset به شرح زیر است:

rudderClient.reset(clearAnonymousId: true);

اگر صرفا می‌خواهید ویژگی‌های کاربر حذف شوند ولی anonymousId حفظ شود، از پارامتر clearAnonymousId: false استفاده نمایید.

rudderClient.reset(clearAnonymousId: false);

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

رویدادهایی با حجم بیشتر از ۳۲ کیلوبایت چه می‌شود؟

✅ Zebline Flutter SDK به‌طور خودکار رویدادهایی که حجم آن‌ها بیش از ۳۲KB باشد را نادیده گرفته و ارسال نمی‌کند.

Flutter SDK Features and Usage

در این بخش، ویژگی‌ها و سناریوهای مختلفی که می‌توان با استفاده از Zebline Flutter SDK پیاده‌سازی کرد، معرفی شده‌اند

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

این قابلیت از نسخه v2.6.0 به بعد در دسترس است.

مراحل فعال‌سازی رمزنگاری دیتابیس:

در فایل pubspec.yaml، پکیج زیر را اضافه کنید:

rudder_plugin_db_encryption: ^1.0.1

اجرای دستور زیر:

flutter pub get

import کردن پکیج:

 import 'package:rudder_plugin_db_encryption/rudder_plugin_db_encryption.dart';

ساخت و استفاده از RudderDBEncryption هنگام مقداردهی اولیه:

RudderDBEncryption dbEncryption = RudderDBEncryption(true, "&lt;encryption_key&gt;");

MobileConfig mc = MobileConfig(dbEncryption: dbEncryption);

RudderConfigBuilder builder = RudderConfigBuilder();

builder

..withDataPlaneUrl("DATA_PLANE_URL")

..withControlPlaneUrl(CONTROL_PLANE_URL)

..withMobileConfig(mc);

rudderClient.initialize("WRITE_KEY", config: builder.build());

کلاس RudderDBEncryption پارامترهای زیر را می‌پذیرد:

Parameter	Type	Description	Default value
enable	bool	Specifies whether to encrypt/decrypt the database.	False
encryption_key	String	Key used to encrypt/decrypt the database.	-

برای حذف رمزنگاری از پایگاه داده، یک شیء از کلاس RudderDBEncryption را با کلید رمزنگاری (encryption key) خود پیکربندی کرده و مقدار پارامتر enable را برابر با false قرار دهید.

راهنمای iOS – حل مشکل اتصال به SQLCipher

پکیج rudder_plugin_db_encryption برای رمزنگاری از Cocoapod مربوط به SQLCipher استفاده می‌کند.
اگر به‌طور ناخواسته به SQLite استاندارد لینک شده باشید، رمزنگاری عمل نمی‌کند.

خطای قابل مشاهده:

RSDBPersistentManager: createDB: Cannot encrypt the Database as SQLCipher wasn't linked correctly.

راه‌حل:

در تنظیمات Build Settings در سطح پروژه، یکی از دستورهای زیر را در Other Linker Flags اضافه کنید (بسته به سناریو):

Scenario	Command	Notes
When using SQLCipher commercial edition static libraries	$(PROJECT_DIR)/sqlcipher-static-ios/ios-libs/libsqlcipher-ios.a	Adjust according to the path to the libsqlcipher-ios.a you received as a part of the package.
When using the sqlcipher.xcodeproj included in the SQLCipher Git repository	$(BUILT_PRODUCTS_DIR)/libsqlcipher.a	-
When using the SQLCipher CocoaPod with the use_frameworks Podfile setting enabled	-framework SQLCipher	-
When using the SQLCipher CocoaPod without the use_frameworks Podfile setting enabled	-lSQLCipher	-

پس از افزودن فلگ لینک‌دهنده (Linker Flag) به تنظیمات build در سطح پروژه، باید چیزی مشابه تصویر زیر را مشاهده کنید:

Project-level build settings

پس از اضافه کردن فلگ لینک‌دهنده (Linker Flag) به تنظیمات build در سطح پروژه، به تنظیمات build در سطح تارگت (Target) نیز مراجعه کنید و مطمئن شوید که SQLCipher پیش از SQLite در لیست لینک‌ها نمایش داده شده است، مشابه تصویر زیر.

Target-level build settings

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

ویژگی Gzip به طور پیش فرض بر روي موبايل، فعال مي باشد.

Zebline Flutter SDK به طور خودکار درخواست های رویداد را با Gzip فشرده می کند و سپس به سرور ارسال می‌کند. برای غیرفعال کردن این ویژگی، پارامتر Gzip را هنگام مقداردهی اولیه SDK به false تنظیم کنید:

MobileConfig mc = MobileConfig(gzip: false);

RudderConfigBuilder builder = RudderConfigBuilder();

builder

..withDataPlaneUrl("DATA_PLANE_URL")

..withControlPlaneUrl(CONTROL_PLANE_URL)

..withMobileConfig(mc);

rudderClient.initialize("WRITE_KEY", config: builder.build(), options: null);

فعال/غيرفعالسازي رهگيري کاربر (Enabling/disabling user tracking)

زبلاین (Zebline) این امکان را فراهم می‌کند که تا زمانی که کاربر رضایت خود را اعلام نکرده، هیچ‌گونه فعالیتی از او رهگیری (Tracking) نشود. این قابلیت از طریق متد optOut در SDK قابل استفاده است.

ℹ️ نکته:
متد optOut از نسخه‌ی 1.0.6 به بعد در SDK فلاتر در دسترس است.
این متد یک مقدار بولی (Boolean) می‌پذیرد که تعیین می‌کند رهگیری فعالیت‌های کاربر فعال یا غیرفعال باشد.
مقدار این فلگ حتی پس از راه‌اندازی مجدد دستگاه نیز حفظ می‌شود.

🔒 غیرفعال‌سازی رهگیری فعالیت‌های کاربر:

rudderClient.optOut(true);

✅ فعال‌سازی مجدد پس از دریافت رضایت کاربر:

rudderClient.optOut(false);

به این ترتیب می‌توانید طبق قوانین حفظ حریم خصوصی، رهگیری را تنها پس از کسب رضایت صریح کاربر فعال کنید.

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

هنگام ارسال رویدادها به یک مقصد از طریق device mode، می توانید صراحتاً مشخص کنید که کدام رویدادها باید حذف شوند یا اجازه عبور داده شوند.

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

شما می‌توانید از نسخه‌ی 2.4.0 به بعد با استفاده از متد putCustomContext در شیء RudderOption، اطلاعات context سفارشی را به تمام رویدادها اضافه کنید.

به عنوان نمونه، در قطعه کد زیر نحوه‌ی تنظیم context سفارشی و ارسال آن در یک فراخوانی track نمایش داده شده است:

RudderProperty property = RudderProperty();

property.put("manufacturer", "Ford");

property.put("model", "Explorer");

RudderOption options = RudderOption();

options.putCustomContext("address", {

"city": "New Orleans",

"pin": "70032",

"state": {"name": "Louisiana", "code": "LO"},

"country": {"name": "USA", "code": "US"},

"zone": 12,

"lat": 22.5726,

});

rudderClient.track("Purchased Car", properties: property, options: options);

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

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

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

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

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

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

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

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

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

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

در Zebline، شناسه‌ی تبلیغاتی (Advertisement ID) تنها در صورتی به‌صورت خودکار جمع‌آوری می‌شود که هنگام مقداردهی اولیه به SDK، گزینه‌ی autoCollectAdvertId روی true تنظیم شده باشد:

final RudderController rudderClient = RudderController.instance;

MobileConfig mobileConfig = MobileConfig(autoCollectAdvertId: true);

RudderLogger.init(RudderLogger.VERBOSE);

RudderConfigBuilder builder = RudderConfigBuilder();

builder.withDataPlaneUrl(DATA_PLANE_URL);

builder.withControlPlaneUrl(CONTROL_PLANE_URL)

builder.withTrackLifecycleEvents(true);

rudderClient.initialize(WRITE_KEY,config: builder.build());

برای ارسال صریح شناسه تبلیغاتی دستگاه، می‌توانید از متد putAdvertisingId در SDK استفاده کنید.

این متد یک آرگومان از نوع رشته‌ای (String) با مقدار <ADVERTISING_ID> دریافت می‌کند که معادل شناسه تبلیغاتی اندروید (AAID) یا شناسه تبلیغاتی iOS (IDFA) است.

مثال زیر نحوه‌ی استفاده از putAdvertisingId را نشان می‌دهد:

rudderClient.putAdvertisingId(&lt;ADVERTISING_ID&gt;);

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

شما می توانید device-token خود را جهت ارسال push notification به مقاصدی که از push notification پشتیبانی می کنند، مشخص نماييد. ما token را در context.device.token تنظیم می کنیم.

قطعه کد زیر را دنبال کنید:

rudderClient.putDeviceToken(&lt;DEVICE_TOKEN&gt;);

عيب یابي(Debugging)

اگر با هرگونه مشکلی در مورد Zebline Flutter SDK مواجه شدید، می توانید ورودی VERBOSE یا DEBUG را برای پیدا کردن مشکل فعال کنید. برای فعال کردن ورودی، راه اندازي اوليه RudderClient خود را به شکل زیر تغییر دهید:

اگر هنگام استفاده از SDK فلاتر با مشکلی مواجه شدید، می‌توانید ویژگی ثبت لاگ (logging) را فعال کنید تا دلیل خطا را شناسایی نمایید. برای این کار مراحل زیر را دنبال کنید:

وارد کردن RudderLogger با اجراي دستور زیر:

import 'package:rudder_sdk_flutter/RudderLogger.dart';

فعال‌سازی لاگ‌برداری هنگام مقداردهی اولیه SDK:

RudderConfigBuilder builder = RudderConfigBuilder();

builder.withDataPlaneUrl(DATA_PLANE_URL);

builder.withControlPlaneUrl(CONTROL_PLANE_URL)

builder.withLogLevel(RudderLogger.VERBOSE);

rudderClient.initialize(WRITE_KEY,

config: builder.build());

سطح لاگ (Log Level) را می‌توانید به یکی از مقادیر زیر تنظیم کنید:

NONE
ERROR
WARN
INFO
DEBUG
VERBOSE

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

چه نسخه ای از اندروید برای نصب SDK اندروید Zebline لازم است؟

ما در حال حاضر API 14 اندروید 4.0 (IceCreamSandwich) یا بالاتر را پشتیبانی می کنیم.

آیا می‌توان رمزنگاری را فقط روی دیتابیس‌های جدید اعمال کرد؟

خیر، رمزنگاری دیتابیس هم روی پایگاه‌داده‌های جدید و هم موجود قابل اعمال است. برای این کار، باید شیء RudderDBEncryption را هنگام مقداردهی اولیه SDK به آن پاس دهید.

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

بله، این امکان وجود دارد. اگر دیتابیس قبلاً رمزنگاری شده باشد، می‌توانید با مقداردهی RudderDBEncryption با کلید رمزگشایی مربوطه و تنظیم گزینه‌ی enable روی false، دیتابیس را رمزگشایی (decryption) کنید.

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

پس از رمزنگاری دیتابیس:

اگر هیچ کلیدی ارائه نشود، SDK دیتابیس فعلی که شامل رویدادهای ارسال‌نشده است را حذف کرده و یک دیتابیس غیررمزنگاری‌شده جدید ایجاد می‌کند.
اگر یک کلید اشتباه ارائه شود، SDK دیتابیس فعلی را حذف کرده و یک دیتابیس رمزنگاری‌شده جدید با کلید ارائه‌شده ایجاد می‌کند.

آیا Zebline Flutter SDK از رویدادهای Impression پشتیبانی می‌کند؟

خیر، در حال حاضر Zebline Flutter SDK از رویدادهای Impression پشتیبانی نمی‌کند.

Direct/fresh ↑
nested object ↑

SDK فلاتر

SDK فلاتر (flutter SDK)

مقدمه

Flutter SDK Installation

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

نصب SDK(Installing the SDK)​

مقداردهی اولیه (Initialization) SDK​

گزینه‌های پیکربندی اولیه SDK​

پارامترهای mobileConfig​

پارامترهای webConfig​

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

Flutter SDK API

شناسایی (Identify)​

تنظیم شناسه ناشناس(Setting a custom anonymous Id)​

نحوه‌ی تعیین شناسه دستگاه (deviceId) در اندروید و iOS :​

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

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

دریافت ویژگی‌های کاربر (Obtaining user traits)​

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

رديابي (Track)​

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

گروه (Group)​

بازنشاني Reset​

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

Flutter SDK Features and Usage

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

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

فعال/غيرفعالسازي رهگيري کاربر (Enabling/disabling user tracking)​

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

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

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

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

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

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

عيب یابي(Debugging)​

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

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

نصب SDK(Installing the SDK)

مقداردهی اولیه (Initialization) SDK

گزینه‌های پیکربندی اولیه SDK

پارامترهای mobileConfig

پارامترهای webConfig

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

شناسایی (Identify)

تنظیم شناسه ناشناس(Setting a custom anonymous Id)

نحوه‌ی تعیین شناسه دستگاه (deviceId) در اندروید و iOS :

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

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

دریافت ویژگی‌های کاربر (Obtaining user traits)

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

رديابي (Track)

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

گروه (Group)

بازنشاني Reset

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

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

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

فعال/غيرفعالسازي رهگيري کاربر (Enabling/disabling user tracking)

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

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

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

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

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

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

عيب یابي(Debugging)

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