راهنمای اسکریپت آنالیتیکس یکتانت
اسکریپت آنالتیکس یکتانت
توضیحات اولیه
اسکریپت آنالتیکس یکتانت، یک فایل جاوااسکریپتی کوچک است (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 نمونههای نامعتبر: | 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، اطلاعات خرید را به یکتانت ارسال کنید و از آنها برای کمپینهای ریتارگتینگ دیگر خود و هدفگذاری بر روی مشتریان با ارزش خود استفاده کنید.
یک مثال
از طریق این 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” باشد.