مستندات اتصال

 

{
“items” : [
  {
    "itemId": "string",
    "name": "string",
    "quantity": "number",
    "price": "number",// Toman
    "discountPercentage": "number",
    "discountValue": "number",
    "fullPath": "string",
    "imagesUrl": ["string"],
    "isConsumable": Boolean,
    "consumeTime": Number // -1 for not consumable items
  }
]
}

{
“users” : [
 {
    "userId": "string",
    "firstName": "string",
    "lastName": "string",
    "mobile": "string",
    "email": "string",
    "country": "string",
    "state": "string",
    "city": "string",
    "address": "string",
    "zipCode": "string",
    "company": {"string",
    "companyType": "string",
    "jobPosition": "string",
    "department": "string",
    "industry": "string",
    "birthDate": date,
    "gender": "string",
    "userType": "string", // visitor or customer (customer has at least one purchase)
    "attributes": {
      "customeField1": "string",
      "customeField2": "boolean",
      "customeField3": {"JSON": "value"},
      "customeField4": ["array"]
     }
  }
]
}

 {
"events" : [
        {
            "userId": "string",
            "name": "purchaseApproved",
            "itemIdList": ["itemId1", "itemId2", ... ],
            "time": 'yyyy-mm-ddThh:mm:ss'; // ISO 8601 string
            "properties": {
            "purchaseId": "string",
            "itemsList": [
                    {
                        "itemName",
                        "itemPrice",
                        "itemCount",
                        "itemUrl",
                        "itemImageUrl"
                    }
                ],
            "totalPrice": number, // Toman
            "totalQuantity": number,
            "couponCode": "string",
            "couponPercentage": number,
            "couponValue": number,
            }
        }
    ]
}

 

{
  "itemId": "string",
  "name": "string",
  "quantity": "number",
  "price": "number",// Toman
  "discountPercentage": "number",
  "discountValue": "number",
  "fullPath": "string",
  "imagesUrl": ["string"],
  "isConsumable": Boolean,
  "consumeTime": Number // -1 for not consumable items
}

{
    "userId": "string",
    "firstName": "string",
    "lastName": "string",
    "mobile": "string",
    "email": "string",
    "country": "string",
    "state": "string",
    "city": "string",
    "address": "string",
    "zipCode": "string",
    "company": {"string",
    "companyType": "string",
    "jobPosition": "string",
    "department": "string",
    "industry": "string",
    "birthDate": date,
    "gender": "string",
    "userType": "string", // visitor or customer (customer has at least one purchase)
  "attributes": {
    "customeField1": "string",
    "customeField2": "boolean",
    "customeField3": {"JSON": "value"},
    "customeField4": ["array"]
  }
}

 

{ 
“anonymousId”:"novinAnonymousIdCookieValue",
"name":"eventName",
"properties": {
}
}

 
{ 
"userId":"yourDBUserId",
“anonymousId”:"novinAnonymousIdCookieValue",
"name":"eventName",
"properties": {
}
}

نکات مهم

در هنگام ارسال ایونت می‌توان تنها anonymousId یا تنها userId یا همزمان هر دو را ارسال کرد. اما این نکته را در نظر بگیرید که اگر در زمان ارسال ایونت به هرکدام دسترسی دارید باید حتما ارسال کنید. مثلا اگر ایونت registerorder ارسال می‌کنید چونکه هم به userId و هم به anonymousId دسترسی دارید حتما باید هر دو ارسال شود اما زمانی ممکن است ایونت‌های مثل purchaseApproved، orderSent یا 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 قرار بگیرد.

در ادامه best practice ایونت های یک فروشگاه ایکامرسی را برای مثال آورده‌ایم. لزومی ندارد این ایونت‌ها دقیقا در بزینس شما نیز استفاده شود و می‌تواند ایونت با نام متفاوت و از همه مهمتر  با properties  متفاوت ارسال شود.

Header: Authorization: Bearer accessToken

—-------------------------------- pageView       —---------------------------

ایونت pageView را تنها زمانی ارسال کنید که کاربر از قبل لاگین باشد. یعنی ابتدا چک کنید اگر کاربر لاگین است این ایونت ارسال شود و باید حتما در body درخواست هر دو پارامتر userId و anonymousId وجود داشته باشد.

Body: {
"userId":"string",
"anonymousId":"string",
"name":"pageView",
“novinAB”: "novinABCookieValue",
"properties": {
    “fullUrl”:"string”
  }
}

—-------------------------------- categoryView       —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"categoryView",
“novinAB”: "novinABCookieValue",
“categoryId”:"string”,
"properties": {
    “categoryName”: “string”,
    “fullUrl”:"string”
  }
}
—-------------------------------- itemView       —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"itemView",
“itemId”:"string”,
“novinAB”: "novinABCookieValue",
"properties": {
    “itemName”:"string”,
    "itemUrl": "string",
    "itemImageUrl":"string",
    “fullUrl”:"string”,
  }
}
—-------------------------------- itemAddToCart       —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"itemAddToCart",
“itemId”:"string”,
“novinAB”: "novinABCookieValue",
"properties": {
    “itemName”:"string”,
    “itemsList”: [
                    {
                        "itemId",
                       "itemName",
                        "itemPrice",
                        "itemCount",
                        "itemImageUrl",
                        "itemUrl"
                    },
                    {
                        "itemId",
                       "itemName",
                       "itemName",
                        "itemPrice",
                        "itemCount",
                        "itemImageUrl",
                        "itemUrl"
                    }
    ] // آیتم های موجود در سبد خرید
  }
}
—-------------------------------- itemAddToWishList       —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"itemAddToWishList",
“itemId”:"string”,
“novinAB”: "novinABCookieValue",
"properties": {
    “itemName”:"string”,
    “itemsList”: [
                    {
                        "itemId",
                       "itemName",
                        "itemPrice",
                        "itemCount",
                        "itemImageUrl",
                        "itemUrl"
                    },
                    {
                        "itemId",
                       "itemName",
                       "itemName",
                        "itemPrice",
                        "itemCount",
                        "itemImageUrl",
                        "itemUrl"
                    }
    ] // آیتم های موجود در لیست دلخواه
  }
}
—-------------------------------- itemRemoveFromCart       —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"itemRemoveFromCart",
“itemId”:"string”,
“novinAB”: "novinABCookieValue",
"properties": {
    “itemName”:"string”,
   }
}
—-------------------------------- checkOut      —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"checkOut",
“novinAB”: "novinABCookieValue",
"itemIdList": ["itemId1", "itemId2", ... ],
"properties": {
    “stepNumber”:  number,
    “stepTitle”:"string",
    “itemsList”: [
                    {
                        "itemId",
                       "itemName",
                        "itemPrice",
                        "itemCount",
                        "itemImageUrl",
                        "itemUrl"
                    },
                    {
                        "itemId",
                       "itemName",
                       "itemName",
                        "itemPrice",
                        "itemCount",
                        "itemImageUrl",
                        "itemUrl"
                    }
    ],
    “totalPrice”: number,// Toman
    “totalQuantity”: number,
    “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",
"itemIdList": ["itemId1", "itemId2", ...],
"properties": {
    “purchaseId”:"string",
    “itemsList”: [
                    {
                        "itemId",
                       "itemName",
                        "itemPrice",
                        "itemCount",
                        "itemImageUrl",
                        "itemUrl"
                    },
                    {
                        "itemId",
                       "itemName",
                       "itemName",
                        "itemPrice",
                        "itemCount",
                        "itemImageUrl",
                        "itemUrl"
                    }
    ],
    “totalPrice”: number,// Toman
    “totalQuantity”: number,
    “couponCode”:"string",
    “couponPercentage”: number,
    “couponValue”: number,
  }
}
—-------------------------------- purchaseComplete: بازگشت از درگاه پرداخت     —---------------------------
Body: {
"userId and/or anonymousId":"string",
"name":"purchaseComplete",
“novinAB”: "novinABCookieValue",
"itemIdList": ["itemId1", "itemId2", ... ],
"properties": {
    “purchaseId”:"string",
    “itemsList”: [
                    {
                        "itemId",
                       "itemName",
                        "itemPrice",
                        "itemCount",
                        "itemImageUrl",
                        "itemUrl"
                    },
                    {
                        "itemId",
                       "itemName",
                       "itemName",
                        "itemPrice",
                        "itemCount",
                        "itemImageUrl",
                        "itemUrl"
                    }
    ],
    “totalPrice”: number,// Toman
    “totalQuantity”: number,
    “couponCode”:"string",
    “couponPercentage”: number,
    “couponValue”: number,
  }
}
—-------------------------------- purchaseApproved: تایید خرید توسط ادمین     —---------------------------
Body: {
"userId":"string",
"name":"purchaseApproved",
"itemIdList": ["itemId1", "itemId2", ... ],
"properties": {
    “purchaseId”:"string",
    “itemsList”: [
                    {
                        "itemId",
                       "itemName",
                        "itemPrice",
                        "itemCount",
                        "itemImageUrl",
                        "itemUrl"
                    },
                    {
                        "itemId",
                       "itemName",
                       "itemName",
                        "itemPrice",
                        "itemCount",
                        "itemImageUrl",
                        "itemUrl"
                    }
     ],
     “totalPrice”: number,// Toman
     “totalQuantity”: number,
     “couponCode”:"string",
     “couponPercentage”: number,
     “couponValue”: number,
  }
}

—--------- itemComment: پس از تایید ادمین    -----------------
Body: {
"userId":"string",
"name":"itemComment",
“itemId”:"string",
“properties”: {
    “itemName”:"string",
 }
}
—------------------ itemRate:  پس از تایید ادمین    —-----------------
Body: {
"userId":"string",
"name":"itemRate",
“itemId”:"string",
"properties": {
 “itemName”:"string",
 “rate”: number
 }
}
—-------------------------------- 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
"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
}
"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",
}

۵. دریافت اطلاعات آیتم‌ها

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

روش: POST

آدرس: https://yourdomain/api/items

بدنه درخواست:

 

{
  "itemIdList": ["itemId1", "itemId2", ... ]
}

بدنه جواب:

 

{
  [
    {
  "itemId": "string",
  "name": "string",
  "quantity": "number",
  "price": "number",// Toman
  "discountPercentage": "number",
  "discountValue": "number",
  "fullPath": "string",
  "imagesUrl": ["string"]
  },
{
  "itemId": "string",
  "name": "string",
  "quantity": "number",
  "price": "number",// Toman
  "discountPercentage": "number",
  "discountValue": "number",
  "fullPath": "string",
  "imagesUrl": ["string"]
  } ]}

Body: {
...
"workFlowPath":"webhook/workFlowPathName"
}

 
{
  "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
    },
  ],
}