مستندات اتصال به سرویس نوین مارکتینگ
به منظور دنبال کردن کاربران سایت و همچنین ارسال پوش نوتیفیکیشن به کاربران باید ابتدا اسکریپت زیر را در header سایت قرار دهید.
<script>
function setCookie(cookieName, cookieValue, expirationDays) {
const d = new Date();
d.setTime(d.getTime() + (expirationDays * 24 * 60 * 60 * 1000));
const expires = "expires=" + d.toUTCString();
document.cookie = cookieName + "=" + cookieValue + ";" + expires + ";path=/";
}
function fetchSdkVersion() {
return fetch('https://cdp.novin.marketing/api/sdk')
.then(response => {
if (!response.ok) {
console.log('Failed to fetch SDK version');
return '1.0.0';
}
return response.json();
})
.then(data => {
console.log("data.sdkVersion: " + data.sdkVersion);
return data.sdkVersion;
})
.catch(error => {
console.error('Error fetching SDK version:', error);
return '1.0.0'; // Fallback value
});
}
setCookie('novinProjectId', 'novinProjectToken', 365);
setCookie('novinWPPlugin', 'true', 365); // If your website is WordPress and uses wp-novin plugin
fetchSdkVersion().then(sdkVersion => {
const automationScript = document.createElement('script');
automationScript.src = 'https://cdn.novin.marketing/novinSDK.js?version=' + sdkVersion;
document.head.appendChild(automationScript);
});
</script>
همچنین باید فایل سرویس ورکر را در ریشه اصلی سایت قرار دهید طوریکه با آدرس زیر به آن دسترسی داشته باشیم.
برای ارسال اطلاعات به پلتفرم دادهی مشتریان (CDP) نوین مارکتینگ، به یک accessToken مخصوص پروژهی شما نیاز است.
در همهی درخواستها، مقدار ‘Bearer accessToken’ را در هدر با کلید Authorization قرار دهید.
۱. ارسال دادهها به صورت بالک
نکته: در ارسال بالک، آرایهی ارسالی حداکثر ۱۰۰ المان داشته باشد و از await برای ارسال استفاده نمایید.
ارسال دسته محصولات:
روش: POST
آدرس: https://cdp.novin.marketing/api/categories/bulk
بدنه درخواست:
{ “categories” : [ { "categoryId": "string", "name": "string", "description": "string", "imageURL": "string" } ] }
ارسال برند محصولات
روش: POST
آدرس: https://cdp.novin.marketing/api/brands/bulk
بدنه درخواست:
{
“brands” : [
{
"brandId": "string",
"name": "string",
"description": "string",
"imageURL": "string"
}
]
}
ارسال محصولات
روش: POST
آدرس: https://cdp.novin.marketing/api/items/bulk
بدنه درخواست:
{
“items” : [
{
"itemId": "string",
"name": "string",
"shortName": "string",
"description": "string",
"weight": "number",
"color": "string",
"size": "number",
"quantity": "number",
"keywords": ["string"],
"tags": ["string"],
"brandId": "string",
"SKU": "string",
"price": "number",// Toman
"rate": "number",
"reviews": ["string"],
"discountPercentage": "number",
"discountValue": "number",
"categoryIds": ["string"],
"fullPath": "string",
"imagesUrl": ["string"],
"videosUrl": ["string"]
}
]
}
ارسال کاربران
روش: POST
آدرس: https://cdp.novin.marketing/api/users/bulk
بدنه درخواست:
{
“users” : [
{
"userId": "string",
"firstName": {"value": "string"},
"lastName": {"value": "string"},
"mobile": {"value": "string"},
"email": {"value": "string"},
"country": {"value": "string"},
"state": {"value": "string"},
"city": {"value": "string"},
"address": {"value": "string"},
"zipCode": {"value": "string"},
"company": {"value": "string"},
"companyType": {"value": "string"},
"jobPosition": {"value": "string"},
"department": {"value": "string"},
"industry": {"value": "string"},
"birthDate": {"value": "date"},
"gender": {"value": "string"},
"userType": {"value": "string"}, // visitor or customer (customer has at least one purchase)
"attributes": {
"customeField1": "string",
"customeField2": "boolean",
"customeField3": {"JSON": "value"},
"customeField4": ["array"]
}
}
]
}
ارسال تاریخچه خرید مشتریان
تمام خریدهای قبلی مشتریان به صورت bulk ارسال شود
روش: POST
آدرس: https://cdp.novin.marketing/api/events/bulk
{
"events" : [
{
"userId": "string",
"name": "purchaseComplete",
"time": 'yyyy-mm-ddThh:mm:ss'; // ISO 8601 string
"properties": {
"purchaseId": "string",
"purchaseStatus": "string",
"itemsList": [
{
"itemId",
"itemName",
"itemPrice",
"itemCount"
}
],
"paymentType": "string",
"totalPrice": number, // Toman
"totalPriceWithoutTax": number,// Toman
"totalQuantity": number,
"taxValue": number,
"shippingType": "string",
"shippingCost": number,
"shippingCountry": "string",
"shippingCity": "string",
"couponCode": "string",
"couponPercentage": number,
"couponValue": number,
}
}
]
}
۲. ارسال و آپدیت دادهها
ارسال دسته محصول
روش: POST
آدرس: https://cdp.novin.marketing/api/categories
بدنه درخواست:
{
"categoryId": "string",
"name": "string",
"description": "string",
}
ارسال برند محصول
روش: POST
آدرس: https://cdp.novin.marketing/api/brands
بدنه درخواست:
{
"brandId": "string",
"name": "string",
"description": "string",
"imageURL": "string"
}
ارسال محصول
روش: POST
آدرس: https://cdp.novin.marketing/api/items
بدنه درخواست:
{
"itemId": "string",
"name": "string",
"shortName": "string",
"description": "string",
"weight": "number",
"color": "string",
"size": "number",
"quantity": "number",
"keywords": ["string"],
"tags": ["string"],
"brandId": "string",
"SKU": "string",
"price": "number",// Toman
"rate": "number",
"reviews": ["string"],
"discountPercentage": "number",
"discountValue": "number",
"categoryIds": ["string"],
"fullPath": "string",
"imagesUrl": ["string"],
"videosUrl": ["string"]
}
ارسال کاربر
روش: POST
آدرس: https://cdp.novin.marketing/api/users
بدنه درخواست:
{
"userId": "string",
"firstName": {"value": "string"},
"lastName": {"value": "string"},
"mobile": {"value": "string"},
"email": {"value": "string"},
"country": {"value": "string"},
"state": {"value": "string"},
"city": {"value": "string"},
"address": {"value": "string"},
"zipCode": {"value": "string"},
"company": {"value": "string"},
"companyType": {"value": "string"},
"jobPosition": {"value": "string"},
"department": {"value": "string"},
"industry": {"value": "string"},
"birthDate": {"value": "date"},
"gender": {"value": "string"},
"userType": {"value": "string"}, // visitor or customer (customer has at least one purchase)
"attributes": {
"customeField1": "string",
"customeField2": "boolean",
"customeField3": {"JSON": "value"},
"customeField4": ["array"]
}
}
۳. حذف دادهها
حذف دسته محصول
روش: DELETE
آدرس: https://cdp.novin.marketing/api/categories/{categoryId}
حذف برند محصول
روش: DELETE
آدرس: https://cdp.novin.marketing/api/brands/{brandId}
حذف محصول
روش: DELETE
آدرس: https://cdp.novin.marketing/api/items/{itemId}
حذف کاربر
روش: DELETE
آدرس: https://cdp.novin.marketing/api/users/{userId}
۴. دریافت داده از سیستم شما
به دلایل مختلف ممکن است دادههای محصولات و/یا کاربران سینک نباشند، جهت اطمینان از سینک بودن دیتابیسها، نیاز به پیاده سازی یک سرویس Restful API جهت دریافت user، item، category، brand از سمت شما است.
در پیاده سازی این وب سرویس میتوانید از Bearer Authentication و یک توکن خصوصی جهت امنیت در دسترسی به اطلاعات استفاده نمایید.
دریافت دسته محصول
روش: GET
آدرس: YourBaseUrl/categories/{categoryId}
بدنه پاسخ:
{
"categoryId": "string",
"name": "string",
"description": "string",
}
دریافت برند محصول
روش: GET
آدرس: YourBaseUrl/brands/{brandId}
بدنه پاسخ:
{
"brandId": "string",
"name": "string",
"description": "string",
"imageURL": "string"
}
دریافت محصول
روش: GET
آدرس: YourBaseUrl/items/{itemId}
بدنه پاسخ:
{
"itemId": "string",
"name": "string",
"shortName": "string",
"description": "string",
"weight": "number",
"color": "string",
"size": "number",
"quantity": "number",
"keywords": ["string"],
"tags": ["string"],
"brandId": "string",
"SKU": "string",
"price": "number",// Toman
"rate": "number",
"reviews": ["string"],
"discountPercentage": "number",
"discountValue": "number",
"categoryIds": ["string"],
"fullPath": "string",
"imagesUrl": ["string"],
"videosUrl": ["string"]
}
دریافت کاربر
روش: GET
آدرس: YourBaseUrl/users/{userId}
بدنه پاسخ:
{
"userId": "string",
"firstName": {"value": "string"},
"lastName": {"value": "string"},
"mobile": {"value": "string"},
"email": {"value": "string"},
"country": {"value": "string"},
"state": {"value": "string"},
"city": {"value": "string"},
"address": {"value": "string"},
"zipCode": {"value": "string"},
"company": {"value": "string"},
"companyType": {"value": "string"},
"jobPosition": {"value": "string"},
"department": {"value": "string"},
"industry": {"value": "string"},
"birthDate": {"value": "date"},
"gender": {"value": "string"},
"userType": {"value": "string"}, // visitor or customer (customer has at least one purchase)
}
۵. ارسال ایونتها
در سیستم نوین مارکتینگ اتومیشن، ۲ نوع کاربر داریم. کاربر ناشناس (Anonymous) و کاربر شناس (Identified)
Anonymous: کاربریست که اطلاعات ارتباطی مانند ایمیل، شماره موبایل و … از وی نداریم. برای ذخیره ی تمام رفتارها و ایونت های این کاربر، باید از سمت بک اند مقدار کوکی با نام novinAnonymousId که در واقع AnonymousId کاربر است را دریافت کنید و تمامی ایونت ها را با کلید “anonymousId” و مقدار کوکی ارسال کنید. برای مثال:
{
“anonymousId”:"novinAnonymousIdCookieValue",
"name":"eventName",
"properties": {
}
}
کاربری که در سایت (یا اپلیکیشن) لاگین است کاربر Identified است و در پایگاه داده ی شما یک userId دارد. تمام ایونت های این نوع کاربر با کلید “userId” و Id کاربر (در سیستم خودتان) به همراه anonymousId ارسال کنید. برای مثال:
{
"userId":"yourDBUserId",
“anonymousId”:"novinAnonymousIdCookieValue",
"name":"eventName",
"properties": {
}
}
نکات مهم
در هنگام ارسال ایونت میتوان تنها anonymousId یا تنها userId یا همزمان هر دو را ارسال کرد. اما این نکته را در نظر بگیرید که اگر در زمان ارسال ایونت به هرکدام دسترسی دارید باید حتما ارسال کنید. مثلا اگر ایونت registerorder ارسال میکنید چونکه هم به userId و هم به anonymousId دسترسی دارید حتما باید هر دو ارسال شود اما زمانی ممکن است ایونتهای مثل purchaseComplete یا itemComment پس از تایید ارسال شود. در این زمان به anonymousId کاربر دسترسی نیست، پس میتوان فقط userId را در ایونت ارسال کرد.
نکته بسیار مهم
در هنگام ارسال هر کدام از ایونت ها اگر کاربر لاگین است حتما باید همزمان userId و anonymousId ارسال شوند.
ایونت باید زمانی ارسال شود که کوکی novinAnonymousId موجود باشد. پس قبل از ارسال ایونت باید منتظر بمانید تا این کوکی ست شده باشد. این اتفاق فقط برای اولین بازدید کاربر از سایت شما چالش برانگیز می شود و در بقیه ی وارد کاربر حتما این کوکی را دارد.
در صورت نیاز به تست A/B حتما در هنگام ارسالِ ایونت ها، پارامتر novinAB را نیز ارسال کنید که مقدار این پارامتر با خواندن کوکی با نام novin-AB بدست میآید.
روشهای ارسال ایونت
ارسال ایونت به CDP نوین میتواند از سمت فرانتاِند یا بکاِند صورت پذیرد.
فرانتاِند:
در صورتیکه به پارامترهای مورد نیاز هر ایونت از سمت فرانت دسترسی دارید میتوانید از این روش سادهتر برای ارسال ایونت استفاده کنید.در این روش میتوانید از SDK نوین استفاده کنید. به این منظور دستور ()novin.event.send که در window موجود است را با پارامترهای مشخص شده برای هر ایونت که در ادامه با عنوان body مشخص شده است، اجرا نمایید. در این روش نیازی به ارسال token نیست.
نکته: در صورت استفاده از SDK برای ارسال ایونت نیازی به قراردادن پارامترهای anonymousId و novinAB نیست. SDK به صورت خودکار این پارامترها را در body اضاف میکند.
نکته: ایونت purchaseComplete از سمت فرانت قابل ارسال نیست.
بکاِند:
برای ارسال ایونت از سمت بکاِند از وبسرویس نوین با مشخصات زیر استفاده کنید. پارامترهای مشخص شده برای هر ایونت در ادامه مشخص شده است. در این روش باید حتما token در header قرار بگیرد.
وبسرویس ارسال ایونت و پارامترهای هر ایونت
Method: POST
Endpoint: https://cdp.novin.marketing/api/events
Header: Authorization: Bearer accessToken
—-------------------------------- pageView —---------------------------
ایونت pageView را تنها زمانی ارسال کنید که کاربر از قبل لاگین باشد. یعنی ابتدا چک کنید اگر کاربر لاگین است این ایونت ارسال شود و باید حتما در body درخواست هر دو پارامتر userId و anonymousId وجود داشته باشد.
Body: {
"userId":"string",
"anonymousId":"string",
"name":"pageView",
“novinAB”: "novinABCookieValue",
"properties": {
“fullUrl”:"string”,
“device”:“string”,
“OS:“string”,
“Browser”:“string”,
}
}
—-------------------------------- categoryView —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"categoryView",
“novinAB”: "novinABCookieValue",
“categoryId”:"string”,
"properties": {
“categoryName”: “string”,
“fullUrl”:"string”,
“device”:“string”,
“OS:“string”,
“Browser”:“string”,
}
}
—-------------------------------- itemView —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"itemView",
“itemId”:"string”,
“novinAB”: "novinABCookieValue",
"properties": {
“itemName”:"string”,
“fullUrl”:"string”,
“device”:“string”,
“OS:“string”,
“Browser”:“string”,
}
}
—-------------------------------- itemAddToCart —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"itemAddToCart",
“itemId”:"string”,
“novinAB”: "novinABCookieValue",
"properties": {
“itemName”:"string”,
“itemsList”: [
{
"itemId",
"itemName",
"itemPrice",
"itemCount"
}
] // آیتم های موجود در سبد خرید
{
"itemId",
"itemName",
"itemName",
"itemPrice",
"itemCount"
}
] // آیتم های موجود در سبد خرید
}
}
—-------------------------------- itemAddToWishList —---------------------------
Body: {
"userId":"string",
"name":"itemAddToWishList",
“itemId”:"string”,
“novinAB”: "novinABCookieValue",
"properties": {
“itemName”:"string”,
“itemsList”: [
{
"itemId",
"itemName",
"itemPrice",
"itemCount"
}
] // آیتم های موجود در لیست دلخواه
{
"itemId",
"itemName",
"itemName",
"itemPrice",
"itemCount"
}
] // آیتم های موجود در لیست دلخواه
}
}
—-------------------------------- itemRemoveFromCart —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"itemRemoveFromCart",
“itemId”:"string”,
“novinAB”: "novinABCookieValue",
"properties": {
“itemName”:"string”,
“itemsList”: [
{
"itemId",
"itemName",
"itemPrice",
"itemCount"
}
] // آیتم های موجود در سبد خرید
{
"itemId",
"itemName",
"itemName",
"itemPrice",
"itemCount"
}
] // آیتم های موجود در سبد خرید
}
}
—-------------------------------- checkOut —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"checkOut",
“novinAB”: "novinABCookieValue",
"properties": {
“stepNumber”: number,
“stepTitle”:"string",
“itemsList”: [
{
"itemId",
"itemName",
"itemPrice",
"itemCount"
},
{
"itemId",
"itemName",
"itemName",
"itemPrice",
"itemCount"
}
],
“paymentType”:"string",
“totalPrice”: number,// Toman
“totalPriceWithoutTax”: number,// Toman
“totalQuantity”: number,
“taxValue”: number,
“shippingType”:"string",
“shippingCost”: number,
“shippingCountry”:"string",
“shippingCity”:"string",
“couponCode”:"string",
“couponPercentage”: number,
“couponValue”: number,
}
}
—-------------------------------- couponApplied —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"couponApplied",
“novinAB”: "novinABCookieValue",
"properties": { ,
“couponCode”:"string",
“couponCategory”:"string",
“couponPercentage”: number,
“couponValue”: number,
}
}
—-------------------------------- couponNotApplied —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"couponApplied",
“novinAB”: "novinABCookieValue",
"properties": { ,
“couponCode”:"string",
“couponCategory”:"string",
“couponPercentage”: number,
“couponValue”: number,
“reason”:"string"
}
}
—-------------------------------- registerOrder —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"registerOrder",
“novinAB”: "novinABCookieValue",
"properties": {
“purchaseId”:"string",
“itemsList”: [
{
"itemId",
"itemName",
"itemPrice",
"itemCount"
},
{
"itemId",
"itemName",
"itemName",
"itemPrice",
"itemCount"
}
],
“paymentType”:"string",
“totalPrice”: number,// Toman
“totalPriceWithoutTax”: number,// Toman
“totalQuantity”: number,
“taxValue”: number,
“shippingType”:"string",
“shippingCost”: number,
“shippingCountry”:"string",
“shippingCity”:"string",
“couponCode”:"string",
“couponPercentage”: number,
“couponValue”: number,
}
}
—-------------------------------- purchaseComplete —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"purchaseComplete",
“novinAB”: "novinABCookieValue",
"properties": {
“purchaseId”:"string",
“purchaseStatus”:"string",
“itemsList”: [
{
"itemId",
"itemName",
"itemPrice",
"itemCount"
},
{
"itemId",
"itemName",
"itemName",
"itemPrice",
"itemCount"
}
],
“paymentType”:"string",
“totalPrice”: number,// Toman
“totalPriceWithoutTax”: number,// Toman
“totalQuantity”: number,
“taxValue”: number,
“shippingType”:"string",
“shippingCost”: number,
“shippingCountry”:"string",
“shippingCity”:"string",
“couponCode”:"string",
“couponPercentage”: number,
“couponValue”: number,
}
}
—--------- itemComment (optional -Recommender & Club) -----------------
Body: {
"userId and/or anonymousId":"string",
"name":"itemComment",
“itemId”:"string",
“novinAB”: "novinABCookieValue",
“properties”: {
“itemName”:"string",
}
}
—------------------ itemRate (optional -Recommender & Club) —-----------------
Body: {
"userId and/or anonymousId":"string",
"name":"itemRate",
“itemId”:"string",
“novinAB”: "novinABCookieValue",
"properties": {
“itemName”:"string",
“rating”: number
}
}
—------------------ itemCommentsClick (optional -Recommender) ----------------
Body: {
"userId and/or anonymousId": "string",
"name": "itemCommentsClick",
"itemId": "string",
“novinAB”: "novinABCookieValue",
},
—------------------ itemSpecificAtionsClick (optional -Recommender) —--------------------
Body: {
"userId and/or anonymousId": "string",
"name": "itemSpecificationsClick",
"itemId": "string",
“novinAB”: "novinABCookieValue",
},
—------------------------- itemScroll (optional -Recommender) —-----------------{
Body: {
"userId and/or anonymousId": "string",
"name": "itemScroll",
"itemId": "string",
“novinAB”: "novinABCookieValue",
"properties": {
“scrollPerCent”: “number”,
}
},
ارسال ایونت برای اسکرول 25، 50، 75 و 100 درصد
—----------------------- itemShare (optional -Recommender & Club) ---------------------
Body: {
"userId and/or anonymousId": "string",
"name": "itemShare",
"itemId": "string",
“novinAB”: "novinABCookieValue",
"properties": {
“itemName”:"string",
}
},
—---------------- itemTimeOnPage (optional -Recommender) —-------------------
Body: {
"userId and/or anonymousId": "string",
"name": "itemTimeOnPage",
"itemId": "string",
“novinAB”: "novinABCookieValue",
"properties": {
“timeOnPage”:"number",
}
},
ارسال ایونت برای زمان های 15، 30، 45 و 60 ثانیه
—------------------- itemDownload (optional -Recommender) —-------------------
Body: {
"userId and/or anonymousId": "string",
"name": "itemDownload",
"itemId": "string",
“novinAB”: "novinABCookieValue",
}
—-------------------------------- searchItem —---------------------------
Body: {
"userId and/or anonymousId":"string",
"Name":"search",
“novinAB”: "novinABCookieValue",
"properties": {
“searchQuery”:"string”
}
}
—-------------------------------- tryToSignUp —---------------------------
Body: {
"anonymousId":"anonymousId",
"name":"tryToSignUp",
“novinAB”: "novinABCookieValue",
"properties": {
"mobile": string, // if availabe
"email": string, // if availabe
"firstName": string, // if availabe
"lastName": string // if availabe
}
}
—-------------------------------- signUp —---------------------------
// both userId and anonymousId are required
Body: {
"userId":"string",
"anonymousId":"anonymousId",
"name":"signUp",
“novinAB”: "novinABCookieValue",
}
—-------------------------------- tryToSignIn —---------------------------
Body: {
"anonymousId":"anonymousId",
"name":"tryToSignIn",
“novinAB”: "novinABCookieValue",
"properties": {
"mobile": string, // if availabe
"email": string, // if availabe
}
}
—-------------------------------- signIn —---------------------------
// both userId and anonymousId are required
Body: {
"userId":"string",
"anonymousId":"anonymousId",
"name":"signIn",
“novinAB”: "novinABCookieValue",
}
—-------------------------------- signOut —---------------------------
Body: {
"userId":"string",
"anonymousId":"anonymousId",
"name":"signOut",
“novinAB”: "novinABCookieValue",
}
—-------------------------------- emailSubscription —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"emailSubscription",
“novinAB”: "novinABCookieValue",
}
—-------------------------------- emailUnsubscription —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"emailUnsubscription",
“novinAB”: "novinABCookieValue",
}
۶. باشگاه مشتریان
به منظور امتیازدهی به هر رفتار کاربر مثل خرید، کامنت گذاری، اشتراک گذاری، دادن سرنخ و … می توان در ارسال ایونت ها از پارامتر aggregations استفاده کرد.
فیلد userAggregationfield و مقدار امتیاز آن برای ایونت های فرانت اندی باید از قبل برای پروژه شما تعریف شود.
در ایونت های فرانت اندی ارسال مقدار point بی اهمیت بوده و مقدار point برای هر userAggregationField از قبل مشخص شده است.
{
"userId or/and anonymousId":"string",
"name": "eventName",
"aggregations": [
{
"userAggregationfield": "mobileLead",
"operation": "+"
},
{
"userAggregationfield": "emailLead",
"operation": "+"
}
],
}
اما برای ایونت های بک اند نیازی به تعریف فیلد نیست و علاوه بر آن می توانند امتیاز را ارسال کنند. همچنین این نوع ایونت ها می توانند چندین بار باعث افزایش یا کاهش مقدار فیلد کاربر شوند.
{
"userId or/and anonymousId":"string",
"name": "eventName",
"aggregations": [
{
"userAggregationfield": "purchasePoints",
"point": 240 // positive or negetive
},
],
}