Skip to content

Latest commit

 

History

History
405 lines (261 loc) · 19.5 KB

README.md

File metadata and controls

405 lines (261 loc) · 19.5 KB
Raw

خلاصه

این راهنمای SDK جاوااسکریپت ادتریس برای وب سایت ها یا برنامه های وب است. می توانید اطلاعات بیشتری در مورد ادتریس را در وبسایت adtrace.io بخوانید.

این مطلب را به زبان های دیگر بخوانید: انگلیسی, فارسی

فهرست مطالب

اپلیکیشن مثال

شما می‌توانید با بررسی برنامه مثال در اینجا بررسی کنید که چگونه SDK ما می‌تواند در برنامه وب استفاده شود.

نصب و راه اندازی

این SDK را می توان برای ردیابی نصب‌ها، سشن‌ها و رویدادها استفاده کرد. به سادگی SDK وب ادتربس را به برنامه وب خود اضافه کنید.

SDK ادتریس تحت تمام تعاریف ماژول قرار دارد، بنابراین در محیط‌های CommonJS و AMD کار می‌کند و همچنین در صورت وارد کردن از طریق تگ script در HTML از طریق متغیر سراسری Adtrace در دسترس است. قبرای نصب SDK وب ادتربس قطعه کد زیر را در نگ head فایل HTML جایگذاری کنید

<script type="application/javascript" src="./dist/adtrace-latest.min.js"></script>

SDK وب ادتربس باید فقط یک بار در هر صفحه بارگیری و راه‌اندازی شود.

همچنین امکان نصب sdk ما از طریق NPM وجود دارد:

npm install web-adtrace --save

و سپس آن را وارد کنید:

import Adtrace from "web-adtrace"

مقداردهی اولیه

برای بکارگیری SDK وب ادتریس باید هر چه زودتر مقداردهی اولیه را با فراخوانی متد Adtrace.initSdk انجام دهید:

Adtrace.initSdk({
  appToken: 'YOUR_APP_TOKEN',
  environment: 'production'
});

مهم: برای اتریبیوشن مناسب، متد setReferrer باید تا حد امکان بلافاصله بعد از initSdk فراخوانی شود..

در اینجا لیست کامل پارامترهای موجود برای متد initSdk آمده است:

پارامترهای اجباری

appToken string

متد مقداردهی اولیه به این پارامتر نیاز دارد، بنابراین مطمئن شوید که appToken را صحیح وارد کنید.

environment string

این پارامتر نیز اجباری است. گزینه های موجود production یا sandbox هستند. در صورتی که در حال آزمایش SDK به صورت لوکال هستید، از sandbox استفاده کنید.

پارامترهای اختیاری

attributionCallback function

این پارامتر یک تابع می پذیرد و آن یک تابع کالبک برای تغییر اتریبیوشن است. دو آرگومان به این تابع callback پاس داده می شود، اولی یک نام رویداد داخلی است (می توان آن را نادیده گرفت)، و دیگری آبجکتی است که اطلاعات مربوط به اتریبیوشن تغییر یافته را در خود نگه می دارد.

مثال:

Adtrace.initSdk({
  // ... other params go here, including mandatory ones
  attributionCallback: function (e, attribution) {
    // e: internal event name, can be ignored
    // attribution: details about the changed attribution
  }
});

defaultTracker string

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

customUrl string

به طور پیش فرض همه درخواست ها به endpoint های ادتریس می روند. شما می توانید تمام درخواست ها را به endpoint سفارشی خود ارسال کنید.

eventDeduplicationListLimit number

به طور پیش‌فرض این پارامتر روی 10 تنظیم شده است. می‌توان این محدودیت را نادیده گرفت، اما مطمئن شوید که عددی مثبت است و خیلی بزرگ نیست. این پارامتر n شناسه کپی شده (تعریف شده توسط این پارامتر) را در حافظه پنهان نگه می دارد و از آنها برای کپی کردن رویدادها با شناسه های تکراری استفاده می کند. logLevel string

به طور پیش فرض این پارامتر روی error تنظیم شده است. مقادیر ممکن none, error, warning, info, verbose هستند. ما به شدت توصیه می‌کنیم که هنگام تست کردن، برای مشاهده گزارش‌های دقیق و اطمینان از اینکه یکپارچه‌سازی به درستی انجام می‌شود، از verbose استفاده کنید. در اینجا جزئیات بیشتری در مورد هر سطح گزارش وجود دارد:

  • verbose - در صورت انجام اقدامات خاص، پیام های دقیق را چاپ می کند
  • info - فقط پیام های اطلاعات اولیه، warning و error را چاپ می کند
  • warning - فقط پیام های warning و error را چاپ می کند
  • error - فقط پیام error را چاپ می کند
  • none - چیزی چاپ نمی شود

logOutput string

خود را ببینید تعریف کنید. این در هنگام تست بر روی دستگاه های تلفن همراه و زمانی که می خواهید گزارش ها را مستقیماً روی صفحه مشاهده کنید مفید است (فقط برای تست توصیه می شود).

مثال:

<div id="log"></div>
Adtrace.initSdk({
  // other initialisation options go here
  logOutput: '#log', // optional
});

namespace string

یک namespace سفارشی برای ذخیره سازی داده های SDK. اگر چندین برنامه در یک دامنه وجود داشته باشد به SDK اجازه می دهد تا حافظه های ذخیره سازی را متمایز کند و داده ها را با هم مخلوط نکند، هر برنامه باید از فضای نام خود استفاده کند.

لطفاً توجه داشته باشید که امکان تنظیم namespace برای فضای ذخیره سازی شده موجود با نام پیش فرض بدون از دست دادن داده وجود دارد. اما پس از تغییر namespace، تغییر نام آن بدون از دست دادن داده ممکن نیست.

externalDeviceId string

شناسه دستگاه خارجی یک مقدار سفارشی است که می توانید به یک دستگاه یا کاربر اختصاص دهید. آنها می توانند به شما کمک کنند تا کاربران را در سشن‌ها و پلتفرم‌ها شناسایی کنید. آنها همچنین می‌توانند به شما کمک کنند تا نصب‌های کاربر تکراری کاربر را تشخیص دهید تا یک کاربر به عنوان چندین نصب جدید حساب نشود.

Adtrace.initSdk({
  // other initialisation options go here
  externalDeviceId: 'YOUR_EXTERNAL_DEVICE_ID', // optional
});

ردیابی رویداد

شما می توانید از ادتریس برای ردیابی رویدادها استفاده کنید. بیایید بگوییم که می خواهید هر ضربه روی یک دکمه خاص را ردیابی کنید. شما می‌توانید یک نشانه رویداد جدید در پنل خود ایجاد کنید که دارای یک نشانه رویداد مرتبط است - چیزی شبیه «abc123».

برای ردیابی این رویداد از برنامه وب خود، باید موارد زیر را انجام دهید:

Adtrace.trackEvent({
  eventToken: 'YOUR_EVENT_TOKEN'
})

مطمئن شوید که ردیابی رویداد را فقط پس ازمقداردهی اولیه SDK ادتریس انجام دهید. در اینجا لیست کامل پارامترهای موجود برای روش trackEvent آمده است:

پارامترهای اجباری

eventToken string

متد trackEvent به این پارامتر نیاز دارد، مطمئن شوید کهeventToken معتبری ارائه می‌کنید.

پارامترهای اختیاری

revenue number

در صورتی که می‌خواهید درآمد را به یک رویداد اختصاص دهید (مثلاً می‌خواهید خریدی را که در داخل برنامه وب شما اتفاق افتاده است ردیابی کنید) باید ارزش مثبتی برای این پارامتر ارائه دهید. همچنین ارائه پارامتر currency که در بلوک بعدی توضیح داده شده است، الزامی است.

currency string

اگر می‌خواهید رویداد درآمد را ردیابی کنید، باید این پارامتر را ارائه دهید. لطفاً از کد ارز معتبر مانند "ًّIRR"، "USD" و غیره استفاده کنید

مثال:

Adtrace.trackEvent({
  // ... other params go here, including mandatory ones
  revenue: 10000,
  currency: "IRR"
})

callbackParams array

شما می‌توانید یک callback URL برای رویدادهای خود در پنل خود ثبت کنید. هر زمان که رویدادی ردیابی شود، یک درخواست GET به آن URL ارسال می کنیم. شما می‌توانید با افزودن پارامتر «callbackParams» به آبجکت ارسال شده به متد «trackEvent»، پارامترهای callback URL را به آن رویداد اضافه کنید. سپس این پارامترها به callback URL شما اضافه خواهد شد.

برای مثال، فرض کنید URL «https://www.mydomain.com/callback» را ثبت کرده‌اید، سپس رویدادی مانند این را ردیابی کنید:

Adtrace.trackEvent({
  // ... other params go here, including mandatory ones
  callbackParams: [
    {key: 'key', value: 'value'}, 
    {key: 'foo', value: 'bar'}
  ]
})

در این صورت ما رویداد را ردیابی می کنیم و درخواستی را به آدرس زیر ارسال می کنیم:

https://www.mydomain.com/callback?key=value&foo=bar

لطفاً توجه داشته باشید که ما هیچ یک از پارامترهای سفارشی شما را ذخیره نمی‌کنیم، بلکه فقط آنها را به تماس‌های شما اضافه می‌کنیم، بنابراین بدون پاسخ به تماس، ذخیره نمی‌شوند و برای شما ارسال نمی‌شوند.

valueParams array

همچنین می توانید پارامترهایی را برای انتقال به network values اضافه کنید که در داشبورد Adtrace شما فعال شده اند. این به طور مشابه با callback parameters ذکر شده در بالا عمل می کند، اما می توان با افزودن پارامتر «valueParams» به آبجکت ارسال شده به متد «trackEvent» اضافه کرد:

Adtrace.trackEvent({
  // ... other params go here, including mandatory ones
  valueParams: [
    {key: 'key', value: 'value'}, 
    {key: 'foo', value: 'bar'}
  ]
})

Global callback parameters

چندین روش برای پارامترهای پاسخ به تماس سراسری مانند افزودن، حذف و پاک کردن آنها وجود دارد. در اینجا لیستی از هر روش موجود است:

addGlobalCallbackParameters

امکان افزودن callback parameters سراری وجود دارد که به طور خودکار به هر درخواست سشن و رویداد اضافه می شود. توجه داشته باشید که callback params مستقیماً به متد «TrackEvent» ارسال می‌شوند، callback params سراسری موجود را لغو می‌کنند. این متد یک «آرایه» با همان قالب پارامتر ['callbackParams'] (#callback-params) از متد «trackEvent» را می‌پذیرد.

مثال:

Adtrace.addGlobalCallbackParameters([
  {key: 'key1', value: 'value1'},
  {key: 'key2', value: 'value2'}
]);

removeGlobalCallbackParameter

برای حذف callback parameter جزیی، از این متد با ارائه کلید یک global callback param که باید حذف شود، استفاده کنید

مثال:

Adtrace.removeGlobalCallbackParameter('key1');

clearGlobalCallbackParameters

به منظور پاک کردن تمام پارامترهای پاسخ به تماس سراسری، به سادگی این روش را فراخوانی کنید

مثال:

Adtrace.clearGlobalCallbackParameters();

Global value parameters

addGlobalValueParameters

این امکان وجود دارد که value parameters سراسری را اضافه کنید، که به طور خودکار به هر درخواست سشن و رویداد اضافه می شود. توجه داشته باشید که value parameter هایی که مستقیماً به متد "trackEvent" ارسال می شوند،global value parameter های موجود را لغو می کنند. این متد یک «آرایه» را با همان قالب پارامتر «valueParams» از متد «trackEvent» می‌پذیرد.

مثال:

Adtrace.addGlobalValueParameters([
  {key: 'key1', value: 'value1'},
  {key: 'key2', value: 'value2'}
]);

removeGlobalValueParameter برای حذف callback parameter جزیی، از این متد با ارائه کلید یک callback param سراسری که باید حذف شود، استفاده کنید

مثال:

Adtrace.removeGlobalValueParameter('key1');

clearGlobalValueParameters

برای پاک کردن تمام value parameters سراسری، به سادگی این روش را فراخوانی کنید

مثال:

Adtrace.clearGlobalValueParameters();

Offline/Online mode

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

switchToOfflineMode

این روش SDK ادتریس را در حالت آفلاین قرار می دهد

مثال:

Adtrace.switchToOfflineMode();

switchBackToOnlineMode

این روش SDK ادتریس را به حالت آنلاین برمی گرداند

Adtrace.switchBackToOnlineMode();

Stop/Restart SDK

در شرایط خاص می توان به طور کامل از اجرای SDK جلوگیری کرد. این بدان معنی است که SDK ردیابی نشست‌ها و رویدادها را متوقف می کند و به طور کلی کار نمی کند. اما امکان راه اندازی مجدد آن پس از مدتی وجود دارد. در اینجا متدهای های موجود برای این عملکرد وجود دارد:

stop

با این کار اجرای SDK ادتریس متوقف می شود

مثال:

Adtrace.stop();

restart

با این کار SDK ادتریس مجددا راه‌اندازی می شود

مثال:

Adtrace.restart();

Get web_uuid

To identify unique web users in Adtrace, Web SDK generates an ID known as web_uuid whenever it tracks first session. The ID is created per subdomain and per browser. The identifier follows the Universally Unique Identifier (UUID) format.

To get web_uuid use the following method:

برای شناسایی کاربران وب منحصر به فرد در Web SDK ادتریس هر زمان که اولین نشست‌ را ردیابی می کند، شناسه ای به نام web_uuid تولید می کند. این شناسه در هر زیر دامنه و هر مرورگر ایجاد می شود. این شناسه از فرمت شناسه منحصر به فرد جهانی (UUID) پیروی می کند.

از روش زیر برای دریافت web_uuid استفاده کنید:

getWebUUID

مثال:

const webUUID = Adtrace.getWebUUID();

اتریبیوشن کاربر

با استفاده از روش زیر می توانید به اطلاعات فعلی اتریبیوشن کاربر خود دسترسی پیدا کنید:

getAttribution

مثال:

const attribution = Adtrace.getAttribution();

Setting referrer

ممکن است بخواهید referrer را تنظیم کنید تا sdk_click را به صورت دستی فعال کند.

برای تنظیم referrer از روش زیر استفاده کنید:

setReferrer

مثال:

Adtrace.setReferrer("adtrace_external_click_id%3DEXTERNAL_CLICK_ID");

لطفاً توجه داشته باشید که referrer باید به درستی با URL رمزگذاری شده باشد.