اسکریپت آنالتیکس یکتانت

توضیحات اولیه

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

پیش‌نیازها

در این مستند، فرض شده است که شما از موارد زیر اطلاعات مقدماتی دارید:

JavaScript
- query selector
- JS variable types
- JSON format
html
- html tags
- meta
- html item props

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

API جزئیات محصول

توضیحات

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

یک مثال

از طریق این API شما می‌توانید اطلاعات محصولات خود را به یکتانت ارسال کنید. نمونه‌ای از نحوه‌ی صدا زدن این API در قطعه کد زیر نمایش داده شده است:

var productInfo = {
    title: "رب گوجه فرنگی قوطی بزرگ",
    sku: "D153-Ij89d", // شناسه محصول
    category: ["مواد غذایی", "رب"],
    price: 11300, // تومان
    brand: "تبرک",
    discount: 30, // درصد
    image: 'https://www.yektanet.com/yektanet-logo.jpg',
    isAvailable: true, // محصول در حال حاضر موجود است

yektanet("product", "detail", productInfo)

این قطعه کد، اطلاعات یک محصول «رب گوجه فرنگی» را به یکتانت ارسال می‌کند. این اطلاعات که در بالا قابل مشاهده است، به ترتیب شامل عنوان، شناسه‌ی محصول، دسته‌بندی محصول، قیمت محصول (به تومان و پس از اعمال تخفیف)، برند محصول، درصد تخفیف محصول، تصویر محصول و موجود بودن یا نبودن محصول است.

API

تمامی اطلاعاتی که از طریق API محصول یکتانت قابل ارسال است، در زیر آمده است:

var productInfo = {
    sku: "Your product SKU",    // unique product Identifier, REQUIRED
    title: "Your product title",
    image: 'Your product image address with http:// or https:// part',
    category: ["category-1", "category-2", "category-3"],   
// list of all categories a product has
// usually you can see those categories in page navigation or breadcrumbs 
    price: 11300,   // Current price with discount
    discount: 30,       // in percent,
    currency: "IRT",    // IRT for Toman, LIMITED SUPPORT
    brand: "a fantastic brand",  // Product's brand
    averageVote: 3.5, 
// average vote on this product,
//SCALE your averageVote to a range [1 - 5] 
    totalVotes: 1345,   // total number of votes
    isAvailable: true,  // is this product available currently?
    expiration: 0 
// a timestamp indicating time of expiration on this product,
// when this product will no longer be available
}

yektanet("product", "detail", productInfo)

تمامی مواردی که از طریق API ثبت محصول یکتانت می‌توانید ارسال کنید، در بالا آمده است. در قسمت زیر، هر کدام از پارامترهای productInfo توضیح داده شده است:

important notes	description	required	value-type	product-field
این شناسه به صورت اجباری باید ارسال شود؛ در غیر این صورت اطلاعات ارسالی شما توسط یکتانت پذیرفته نمی‌شود.	شناسه‌ی یکتای محصول. هر محصول یک شناسه دارد. در صورتی که نمی‌توانید شناسه‌ی محصول‌ها را پیدا کنید، از بخش راهنمای شناسه‌ی محصول استفاده کنید.	yes	string	sku
با استفاده از بخش راهنمای استخراج عنوان محصول می‌توانید راه پیدا کردن عنوان محصول خود را ببینید.	عنوان محصول شما، به عنوان مثال «لپ‌تاپ لنوو مدل AC73» یا «پوشک بچه‌ی بزرگ» می‌توانند عنوان محصول قابل فروش شما باشند.	for retargeting campaigns	string	title
	آدرس اینترنتی تصویر محصول شما. توجه کنید که باید این آدرس را به صورت کامل با پروتکل و دامنه‌ی وب‌سایت بفرستید.	for retargeting campaigns	string	image
	لیستی از دسته‌بندی‌هایی که محصول متعلق به آن دسته‌بندی است. از طریق ارسال این اطلاعات، شما می‌توانید کمپین‌های ریتارگتینگ خود را هدف‌مندتر کنید و فقط برای دسته‌بندی‌های خاصی در نظر بگیرید. همچنین در این صورت اطلاعات تحلیلی سودمندی از دسته‌بندی‌های کاربری و پرطرفدار در اختیار شما قرار داده می‌شود.		list of strings	category
دقت کنید که در حال حاضر این قیمت باید به تومان ارسال شود.			integer	price
این فیلد باید به صورت float ارسال شود و مشخص‌کننده‌ی درصد تخفیف محصول باشد.	درصد تخفیف محصول شما. اگر محصول شما تخفیف ندارد، می‌توانید این فیلد را نفرستید یا آن را برابر با صفر قرار دهید.		float	discount
مقدارهای قابل پذیرش برای این فیلد "IRT"	واحد پولی که در فیلد price مشخص کرده‌اید. در حال حاضر تنها تومان پشتیبانی می‌شود و باید آن را به صورت "IRT" ارسال کنید.		string	currency
	برند محصول شما		string	brand
	اگر کاربران می‌توانند به محصولات شما امتیاز دهند، شما می‌توانید میانگین امتیاز کاربران را از طریق این فیلد و به صورت یک متغیر float ارسال کنید. دقت کنید که امتیاز کاربران باید بین یک تا پنج باشد؛ بنابراین اگر از سیستم امتیاز دیگری استفاده می‌کنید، قبل از ارسال مقیاس آن را تغییر دهید تا بین یک تا پنج قرار بگیرد.		float	averageVote
			integer	totalVotes
	این فیلد نشان می‌دهد که آیا محصول در حال حاضر در فروشگاه برای عرضه موجود است یا خیر. در صورتی که محصول موجود نباشد، محصول در کمپین‌های ریتارگتینگ نمایش داده نمی‌شود.		boolean	isAvailable
با استفاده از راهنمای استخراج فیلد expiration می‌توانید اطلاعات مربوط به زمان اتمام فروش یک محصول را مشخص کنید.	ممکن است که فروش محصولات شما محدودیت داشته باشند؛ به عنوان مثال فروش یک تور می‌تواند تا یک تاریخ مشخص انجام شود. شما می‌توانید تاریخ پایان محصول را از طریق این فیلد ارسال کنید تا محصول شما از آن تاریخ به بعد در کمپین‌های ریتارگتینگ شما نمایش داده نشود.		integer	expiration

sample	product-field
"D-8356-fx56"	sku
"رب گوجه فرنگی قوطی بزرگ"	title
نمونه‌های صحیح: https://yourWebsite.com/images/awesomeImage.jpg http://www.yourWebsite.com/img/icons/logo.png نمونه‌های نامعتبر: ~~yourWebsite.com/images/awesomeImage.jpg~~ ~~/images/awesomeImage.jpg~~ ~~awesomeImage.jpg~~	image
["وسایل الکترونیکی", "کامپیوترهای شخصی", "لپ‌تاپ"]	category
256320	price
27	discount
"IRT"	currency
"gucci"	brand
3.6	averageVote
125	totalVotes
true	isAvailable
1542918600000	expiration

استخراج اطلاعات از صفحه

آماده‌سازی اطلاعات از بک‌اند

اگر تیم فنی شما می‌تواند اطلاعات لازم را در یک قالب مشخص json در اختیار شما قرار دهد، کافی است که این اطلاعات از سمت بک‌اند در یک object ذخیره شوند و در صفحه‌ی مورد نظر در وب‌سایت تحویل داده شود و از طریق yektanet(“product”, “detail”, productInfo) اطلاعات به یکتانت ارسال شود که productInfo همان object ایجاد شده از سمت بک‌اند است.

استخراج sku

شناسه‌ی محصول، یک رشته‌ی یکتا است که برای هر محصول ثابت و مشخص است. این فیلد اجباری است و یکتانت از طریق آن محصولات شما را شناسایی می‌کند. لازم است که شما حتما شناسه‌ی محصولات خود را بفرستید ولی اگر مطمئن هستید که شناسه‌ی محصولات خود را به هیچ عنوان ندارید و نمی‌توانید آن‌ها را ایجاد کنید، می‌توانید از قطعه کد زیر به عنوان sku استفاده کنید. لازم به ذکر است که این روش تنها به حالت محدود همراه است و ممکن است خطاهایی داشته باشد، بنابراین همیشه سعی کنید sku محصولات خود را داشته باشید و در صفحات خود قرار دهید.

String.prototype.ynRemoveURLParameter = function(parameter) {
    var urlparts= this.split('?');
    if (urlparts.length>=2) {
        var prefix= encodeURIComponent(parameter);
        var pars= urlparts[1].split(/[&;]/g);
        for (var i= pars.length; i-- > 0;) { 
            if (pars[i].includes(prefix)) {  
                pars.splice(i, 1);
            }
        }
        url= urlparts[0] + (pars.length > 0 ? '?' + pars.join('&') : "");
        return url;
    } else {
        return this;
    }
}
String.prototype.ynHashCode = function() {
  var hash = 0, i, chr;
  if (this.length === 0) return hash;
  for (i = 0; i < this.length; i++) {
    chr   = this.charCodeAt(i);
    hash  = ((hash << 5) - hash) + chr;
    hash |= 0; 
  }
  return hash;
};
var sku = encodeURI(document.location.host + document.location.pathname +
document.location.search).ynRemoveURLParameter('utm_source').
ynRemoveURLParameter('utm').ynRemoveURLParameter('source').
ynRemoveURLParameter('campaign').ynRemoveURLParameter('medium').
ynHashCode().toString();

استخراج عنوان
معمولا عنوان محصول خود را می‌توانید از راه‌های زیر پیدا کنید:

facebook/twitter meta tag:
- document.querySelector(‘meta[property=”og:title”]’).content
- document.querySelector(‘meta[property=”twitter:title”]’).content
title tags
- document.querySelector(‘title’).text

first h1 or h2 of the page
- document.querySelector(‘h1’).text
- document.querySelector(‘h2’).text

استخراج expiration
این فیلد باید به صورت یک timestamp ارسال شود؛ به عنوان مثال اگر محصول شما در تاریخ ۲۳ اکتبر ۲۰۱۸ تمام می‌شود، می‌توانید از new Date(2018, 10, 23).getTime() استفاده کنید و فیلد را به صورت expiration: new Date(2018, 10, 23).getTime() یا expiration: 1542918600000 بفرستید.

API خرید محصول

توضیحات

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

یک مثال

var purchaseInfo = {
    sku: "D153-Ij89d",  // شناسه محصول
    quantity: 2,
    price: 22600,       // تومان
    currency: "IRT",    // IRT for Toman

yektanet("product", "purchase", purchaseInfo)

این قطعه کد، اطلاعات مربوط به خرید یک محصول را از سوی یک کاربر ارسال می‌کند. در این مثال، کاربری دو محصول با شناسه‌ی مشخص را خرید کرده است و بابت این دو محصول، مبلغ ۲۲۶۰۰ تومان پرداخت کرده است.

API

تمامی اطلاعاتی که از طریق API خرید محصول یکتانت قابل ارسال است، در زیر آمده است:

var purchaseInfo = {
    sku: "Your product SKU",    // unique product Identifier, REQUIRED
    quantity: 2,                // user purchased 2 products 
    price: "Your product's TOTAL price",               
// Current TOTAL price with discount, SHOULD BE ALWAYS IN TOMANS
    currency: "IRT",            // IRT for Toman, LIMITED SUPPORT
}

yektanet("product", "purchase", purchaseInfo)

تمامی مواردی که از طریق API ثبت محصول یکتانت می‌توانید ارسال کنید، در بالا آمده است. در قسمت زیر، هر کدام از پارامترهای purchaseInfo توضیح داده شده است:

important notes	description	required	value-type	product-field
این شناسه به صورت اجباری باید ارسال شود؛ در غیر این صورت اطلاعات ارسالی شما توسط یکتانت پذیرفته نمی‌شود.	شناسه‌ی یکتای محصول. هر محصول یک شناسه دارد. در صورتی که نمی‌توانید شناسه‌ی محصول‌ها را پیدا کنید، از بخش راهنمای شناسه‌ی محصول استفاده کنید.	yes	string	sku
	تعداد محصولی که از طرف کاربر خرید شده است. این فیلد باید به صورت integer ارسال شود.		integer	quantity
دقت کنید که در حال حاضر این قیمت باید به تومان ارسال شود.	قیمت محصول ارسالی که باید integer باشد. دقت کنید که در حال حاضر این قیمت باید به تومان ارسال شود و مجموع هزینه‌ای که کاربر برای آن محصول پرداخت کرده‌است، ارسال شود. به عنوان مثال اگر کاربر از یک محصول 120 هزار تومانی 2 نمونه خرید کرده است، به عنوان مقدار این فیلد باید ‍240000‍ ارسال شود.		integer	price
مقدارهای قابل پذیرش برای این فیلد "IRT"	واحد پولی که در فیلد price مشخص کرده‌اید. در حال حاضر تنها تومان پشتیبانی می‌شود و باید آن را به صورت "IRT" ارسال کنید.		string	currency

sample	product-field
"D-8356-fx56"	sku
1	quantity
256320	price
"IRT"	currency

نکته‌ها

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

نکات مهم

نکاتی که شما باید در استفاده از APIها رعایت کنید و عدم رعایت آن‌ها به باگ و یا ارسال اطلاعات نادرست منجر می‌شود، در زیر آمده است:

همیشه در همه‌ی APIهای مربوط به محصول، شما باید sku را ارسال کنید. sku شناسه‌ی یکتای محصول است که از طریق آن، یکتانت محصول شما را شناسایی می‌کند.
در صورتی که اطلاعات image و title از سوی شما ارسال نشود، همچنان اطلاعات محصولات شما در یکتانت ذخیره می‌شوند ولی به دلیل موجود نبودن اطلاعات این دو فیلد، این محصولات در کمپین‌های ریتارگتینگ شما نمایش داده نمی‌شوند.

محدودیت‌ها

در حال حاضر حتما باید اسکریپت کامل یکتانت (rg.complete.js) بر روی وب‌سایت شما باشد تا بتوانید از قابلیت‌های آنالتیکس یکتانت استفاده کنید.
در حال حاضر قیمت تنها به واحد تومان پشتیبانی می‌شود. بنابراین باید فیلد price به تومان ارسال شود و فیلد currency همیشه برابر با “IRT” باشد.

راهنمای اسکریپت آنالیتیکس یکتانت

اسکریپت آنالتیکس یکتانت

توضیحات اولیه

پیش‌نیازها

API جزئیات محصول

توضیحات

یک مثال

API

استخراج اطلاعات از صفحه

API خرید محصول

توضیحات

یک مثال

API

نکته‌ها

نکات مهم

محدودیت‌ها