آموزش اسکریپت محصول یکتانت (همراه با نمونه)

برای ایجاد و اجرای کمپین‌‌های تبلیغات ریتارگتینگ محصول و محتوامحور محصول، علاوه بر اسکریپت عمومی یکتانت، باید اسکریپت محصول را هم به سایت اضافه کنید.

در این راهنما، با نحوه استفاده و ساخت این اسکریپت همراه با چند مثال آشنا می‌شوید.

توجه: ساخت این اسکریپت نیازمند دانش فنی و تخصصی است. در صورتی که به تیم متخصصی دسترسی ندارید، می‌توانید از طریق بخش «راهنما و پشتیبانی»، درخواست خود را ثبت کنید تا کارشناسان ما، اسکریپت اختصاصی شما را آماده کنند.

 

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

اسکریپت  یکتانت، یک فایل جاوااسکریپتی کوچک است (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 در قطعه کد زیر نمایش داده شده است:

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

 

API

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

در قسمت زیر، هر کدام از پارامترهای productInfo توضیح داده شده است:

Important notes	description	required	value-t	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

در جدول زیر، یک نمونه را مشاهده می‌کنید:

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

 

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

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

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

• استخراج sku

شناسهٔ محصول، یک رشتهٔ یکتا است که برای هر محصول ثابت و مشخص است. این فیلد اجباری است و یکتانت از طریق آن، محصولات شما را شناسایی می‌کند.

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

لازم به ذکر است که این روش تنها به حالت محدود همراه است و ممکن است خطاهایی داشته باشد؛ بنابراین همیشه سعی کنید sku محصولات خود را داشته باشید و در صفحات خود قرار دهید.

• استخراج عنوان

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

• 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

تمامی اطلاعاتی که از طریق 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” باشد.