استریم
بررسی کلی
ایونت چیست؟ ایونت یا رخداد، هر اتفاق مهم در اپلیکیشن و یا سرویس شماست مانند کلیک، خرید، نصب و …
ما جمع‌آوری حجم بالایی از ایونت‌ها را برای شما از همیشه آسان‌تر خواهیم کرد. ایونت‌ها به صورت JSON OBJECT های منحصر به فرد که هر کدام دارای یک timestamp و property هایی است که توسط کاربر تعریف شده‌اند، ارسال می‌شوند. این ایونت‌ها در یک استریم ارسال می‌شوند که می‌توان از آنها در آنالیز استفاده کرد.
نحوه ارسال ایونت در اینگرو
۱- هر درخواست (Request) دارای یک OBJECT JSON منفرد است
۲- انواع مدل‌های داده‌ی پایه‌ای ساپورت می‌شوند. آرایه‌ای از OBJECTها برای آنالیز و فیلتر قابل استفاده نیستند.
۳- Nesting OBJECTS قابل قبول هستند. فقط باید توجه داشته باشید که از پارامترهای ingrow.و lungo. نمیتوانید استفاده کنید.
فهرست مطالب
“ingrow”: {
“project”: “4”,
“stream”: “lungo2”
},
“event”: {
“event_type”: “click”,
“device”: “mobile”,
“product”: “mobile”,
“price” : 63000,
“city” : “Hanetown”
}
}’
اعتبارسنجی
اینگرو از دو روش برای اعتبارسنجی درخواست‌های API ها استفاده می‌کند. که یکی API KEY و دیگری PROJECT ID می‌باشد.
HTTP Header
برای انجام اعتبارسنجی در Header درخواست‌ها باید api-key خود را به روش زیر قرار دهید:
–header ‘api-key: 441a2da7bf77447a62e9602bc06d0059a3b198e9’
نمونه کامل header درخواست مانند نمونه زیر باید باشد:
curl –location –request POST ‘https://event.ingrow.co/v1‘ \
–header ‘Content-Type: application/json’ \
–header ‘api-key: 441a2da7bf77447a62e9602bc06d5559a3b198e9’ \
–header ‘cache-control: no-cache’ \
این کلید به عنوان WRITE KEY در نظر گرفته می‌شود و به ارسال کننده درخواست این اجازه را در صورت معتبر بودن کلید می‌دهد که داده ارسالی را در پایگاه داده ذخیره کند.
API KEY را پس از ساخت پروژه در پنل در تنظیمات پروژه خواهید یافت.
Content-type باید همیشه application/json باشد.
DATA-RAW
در بخش که در BODY درخواست قرار می‌گیرد در یک بخش Project ID و نام Stream قرار می‌گیرد و در بخش دیگر اطلاعات event ارسال می‌شود.
ساختار این بخش مشابه نمونه زیر باید باشد:
–data-raw ‘{
“ingrow”: {
“project”: “4”,
“stream”: “name”
},
“event”: {
“event_type”: “click”,
“device”: “mobile”,
“product”: “mobile”,
“price” : 63000,
“city” : “Tehran”
}
}’
در بخشی که در هر پروژه api-key نمایش داده می‌شود Project ID نیز به کاربر نمایش داده می‌شود که لازم است برای ارسال event این مقدار در بخش ingrow وارد شد.
باید توجه داشته باشید که نام استریم بنا به خواسته شما تشکیل خواهد شد و اگر قصد دارید که در استریمی که اکنون موجود است داده ارسال نمائید باید نام همان استریم را در درخواست ارسال نمائید.
ساختار Event بنا به خواست شما تشکیل خواهد شد. و با هر ساختاری که در هنگام ارسال تشکیل می‌دهید Schema استریم ایجاد می‌شود.
نمونه کامل Curl:
curl –location –request POST ‘https://event.ingrow.co/v1‘ \
–header ‘Content-Type: application/json’ \
–header ‘api-key: 441a2da7bf77447a62e9602bc06d0059a3b198e9’ \
–header ‘cache-control: no-cache’ \
–data-raw ‘{
“ingrow”: {
“project”: “4”,
“stream”: “lungo2”
},
“event”: {
“event_type”: “click”,
“device”: “mobile”,
“product”: “mobile”,
“price” : 63000,
“city” : “Hanetown”
}
}
SDK
ما برای ساده‌تر کردن ارسال ایونت‌ها به اینگرو، SDK های زیادی را برای زبان‌های برنامه‌نویسی مختلف توسعه داده‌ایم. برای دسترسی به این SDK ها بعد از ایجاد اکانت و ورود به اینگرو و ساخت پروژه در بخش install می‌توانید اطلاعات مورد نیاز در مورد نحوه نصب و استفاده از هریک را مطالعه کنید.
SDK ها در واقع یک بسته توسعه نرم‌افزاری (Software Development Kit) هستند که ابزارهای مورد نیاز برای توسعه را در اختیار توسعه دهندگان قرار می‌دهند تا برنامه خود را مطابق با پلتفرم کمپانی هماهنگ کنند.
SDK ها اینگرو در حال عبارتند از:
– JAVA
– GO
– PHP
– Python
– Java Script
– React Native
– Android
– iOS
پروژه‌ها
اولین اقدام برای یکپارچه شدن با پلتفرم اینگرو ساخت پروژه است. پروژه را می‌توان به عنوان سیلوئی از داده‌ها تعریف کرد. داده‌ها در بخش‌هایی به اسم پروژه تفکیک می‌شوند که در هر پروژه تنها به داده‌های آن پروژه دسترسی خواهید داشت.
نکته: در ساخت داشبورد و KPI شما به داده‌های تمام پروژه‌هایتان در Organization دسترسی خواهید داشت.
چند سناریو ممکن است برای تشکیل پروژه‌ها محتمل‌تر باشند:
– اگر شما دارای چند محصول (اپلیکیشن یا سرویس) مختلف هستید برای هر یک از آنها پروژه جدید بسازید.
– شما احتمالا دارای محیط‌های تست و عملیاتی مجزا هستید، می‌توانید برای هر یک از آنها به صورت مجزا پروژه‌ای تشکیل دهید.
– اگر محصول شما در پلتفرم‌های محتلف اجرا می‌شود (اندروید، iOS و PWA و …) ما پیشنهاد می‌کنیم که آنها را در یک پروژه و با استریم‌های متفاوت ارسال کنید که بتوانید گزارش‌های معناداری از آنها دریافت کنید. هیمنطور می‌توانید در یک پروژه و یک استریم تمام داده‌ها را از تمامی پلتفرم‌ها ارسال کنید و برای گزارش‌های دلخواهتان از فیلتر استفاده کنید.
– اگر شما یک محصول دارید که در بخش‌های مختلفی استفاده می‌شود. به طور مثال اپلیکیشنی برای رستوران‌دارها و اپلیکیشنی برای مشتریان دارید. با توجه به گزارش‌های دلخواهتان باید استریم‌ها و پروژه‌هایتان را تشکیل دهید. مثلا می‌توانید برای هر شرکتی که از محصول شما استفاده می‌کند استریم و یا پروژه جداگانه تشکیل دهید.
Event و Event Data
پایگاه داده ما برای ذخیره event data های بهینه‌سازی شده است. ایونت‌ها، رخدادهایی هستند که در لحظه اتفاق می‌افتند. هر ایونت دارای property هایی است که به شما کمک می‌کنند که با استفاده از گزارش‌ها از اتفاقاتی که رخ داده‌اند هرچه با دقت بیشتر مطلع شوید. وقتی از Event Data صحبت می‌کنیم منظور event ها و تمام property هایی است که همراه آنها ارسال می‌شوند.
ایونت‌ها از طریق HTTP POST با URL زیر ارسال می‌شوند:
https://event.ingrow.co/v1
Event و Event Data
Event collection در واقع برای دسته‌بندی داده‌ها مورد استفاده می‌گردد. هر ایونتی متعلق به یک collection خواهند بود. تمام ایونت‌های یک collection توصیف کننده property های یکسان خواهند بود. به عنوان مثال ایونت‌های collection به نام “Login” همگی دارای پارامترهایی مانند :name, user_id, last_name خواهند بود.
Event collection ها باید حتما حاوی یک name باشند و قواعدی دارند که باید رعایت شود:
– اسم آنها باید حداکثر ۶۴ کاراکتر باشد
– نمی‌تواند شامل null value باشد.
ایجاد Event Collection
ایونت کالکشن به صورت اتوماتیک وقتی ایونت برای اینگرو ارسال می‌کنید تشکیل می‌شود.به محض اینکه اولین ایونت را اینگرو دریافت می‌کند، ایونت کالکشن برای انجام آنالیز در دسترس خواهد بود.
Event Properties
property ها بخشی از اطلاعاتی هستند که ایونت را توصیف می‌کنند. شما علاوه بر دانش تحلیلی که نیاز دارید احتیاج به خلاقیت خوبی در تعیین property ها دارید تا بتوانید تشخیص دهید که چه اطلاعاتی را در حال حاضر نیاز دارید و همینطور در آینده به چه اطلاعاتی نیاز پیدا خواهید کرد.
ما محدودیت‌هایی را برای ارسال property لحاظ کرده‌ایم به عنوان مثال نمیتوانید بیش از ۱۰۰۰ property را در یک ایونت ارسال کنید. برای نام‌گذاری property ها باید خلاقیت به خرج دهید و از اسم‌هایی که ممکن است با دیگر property ها تشابه داشته باشند خودداری کنید.
هم‌چنین از نام‌گذاری‌هایی مانند timestamp, session_id , session, event,anonymous, time خودداری کنید زیرا با اطلاعات enrich شده تشابه داشته و شما در گزارش‌گیری دچار خطا می‌کند.
فرمت‌هایی که برای value مجاز هستند ارسال شوند فرمت‌های زیر می‌باشند:
- – String values must be less than 10,000 characters long.
- – Numeric values must be between -2^63 (-9223372036854775808) and 2^63 – 1 (9223372036854775807) (inclusive).
- – array , touple, dictionary are not supported
- – boolean , float, init are supported
- – timestamp date type is based on ISO 8601 Format
- – ISO-8601 Format
فرمت ISO-8601 یک فرمت بین‌المللی استاندارد برای نمایش زمان است که به صورت زیر نمایش داده می‌شود:
- {YYYY}-{MM}-{DD}T{hh}:{mm}:{ss}.{SSS}{TZ}
- YYYY: Four digit year. Example: “2012”
- MM: Two digit month. Example: January would be “01”
- DD: Two digit day. Example: The first of the month would be “01”
- hh: Two digit hour. Example: The hours for 12:01am would be “00” and the hours for 11:15pm would be “23”
- mm: Two digit minute.
- ss: Two digit seconds.
- SSS: Milliseconds to the third decimal place.
- TZ: Time zone offset. Specify a positive or negative integer. To specify UTC, add “Z” to the end. Example: To specify Pacific time (UTC-8 hours), you should append “-0800” to the end of your date string.
توجه داشته باشید که اگر برای time zone مقداری مشخص نکرده باشید، اینگرو آن را به صورت UTC در نظر خواهد گرفت.
نمونه‌ای از موارد ISO-8601:
2012-01-01T00:01:00-08:00
1996-02-29T15:30:00+12:00
2000-05-30T12:12:12Z
اینگرو، این امکان را فراهم کرده است که برخی پیش-پردازش‌ها (Pre-Processing) در ذخیره کرده داده‌ها در پایگاه داده انجام شود. این کار منجر به افزودن اطلاعات ارزشمندی به هر event می‌شود تا بتوانید گزارش‌های دقیق‌تر و بیشتری را دریافت کنید.
این اطلاعات شامل موارد زیر استک
– افزودن anonymous id به ایونت
– افزودن session id به ایونت
– افزودن user id به ایونت
برای این کار باید از متد enrichment اینگرو تبعیت کنید و به دلخواه خود از پلاگین‌های غنی‌سازی داده اینگرو استفاده کنید.
این بخش شامل یک آرایه از object هاست. یک نمونه از enrichment در زیر آورده شده است:
“enrichment”: [{
“name”: “session”,
“input”: {
“anonymous_id”: “anonytest1”,
“user_id”: “”
}
}],
با وارد کردن session برای name به هر ایونتی که ارسال می‌کنید یک session_id افزوده خواهد شد که از این طریق قادر خواهید بود که به توالی رفتار داده‌ها پی ببرید. این id به صورت یکتا تولید شده و هر ۳۰ دقیقه expire خواهد شد.
در بخش input با وارد کردن مقدار anonymous id از سوی کاربر (به عنوان مثال میتواند cookie ارسال شود) شناسه یکتا به کاربری که login نکرده باشد اختصاص داده خواهد شد.
برای اختصاص user id در بخش user_id همراه هر ایونت می توانید آن را ارسال کنید. بعد از این که اولین بار شناسه کاربر را ارسال کردید حتی در صورتی که کاربر لاگین نباشد ما به ایونت های ارسالی از سوی کاربر user_id را ارسال می‌کنیم تا از این طریق توالی رفتارهای کاربران حفظ شود و تا آنجا که بتوانیم مشخص کنیم که چه رفتاری مربوط به چه کاربری است.
یک نمونه از ایونت همراه با enrichment :
{
“ingrow”: {
“project”: “17”,
“stream”: “STR20”
},
“enrichment”: [{
“name”: “session”,
“input”: {
“anonymous_id”: “anon”,
“user_id”: “”
}
}],
“event”: {
“event_type”: “logout”,
“device”: “mobile”,
“product”: “mobile”,
“price” : 37000,
“city” : “NY”
}
}
حالت‌هایی که ما با فرآیند identifier می‌توانیم ایونت‌ها را شناسایی کنیم شامل موارد زیر خواهند بود:
- when user is login and do some action in app
- when user is not login and do some actions in app and then login
- when user has been referred to app and then do some actions and then login
- when user is not login and do some actions in app (identify by anonymous id)
- when user click on adds and refer to install page.
Cast کردن ایونت‌ها
بعد از ارسال اولین ایونت در سیستم استریم تشکیل می‌شود. شمای هر استریم شامل تایپ هر property است.
ما در اینگرو این امکان را داریم که در صورت ارسال اشتباه ایونت با تایپ متفاوت با تایپ اولیه، آنها در حالت‌های زیر cast کرده و از drop شدن آن جلوگیری کند.
| # | type based on the schema | type in received event | action |
| 1 | string | any format except (list, array, JSON, object) | cast to string |
| 2 | int | float | round and cast to int |
| 3 | float | int | cast to float |
| 4 | int | any format except int or float | drop |
| 5 | float | any format except int or float | drop |
| 6 | null | any format | cast to the new format |
| 7 | boolean | any format except boolean | drop |
| 8 | array | any format except array | drop |
| 9 | object | any format except the object | drop |
| 10 | JSON | any format except JSON | drop |
Extend کردن ایونت
بعد از ارسال اولین ایونت در سیستم استریم تشکیل می‌شود. شمای هر استریم شامل تایپ هر property است.
ما در اینگرو این امکان را داریم که در صورت ارسال اشتباه ایونت با تایپ متفاوت با تایپ اولیه، آنها در حالت‌های زیر cast کرده و از drop شدن آن جلوگیری کند.
ساختار ایجاد گزارش
{
“average”: {
“required”: [“target”],
“supports”: [“integer”, “double”]
},
“count”: {
“required”: [],
“supports”: [“integer”, “double”, “string”, “null”]
},
“count_unique”: {
“required”: [“target”],
“supports”: [“integer”, “double”, “string”]
},
“max”: {
“required”: [“target”],
“supports”: [“integer”, “double”]
},
“median”: {
“required”: [“target”],
“supports”: [“integer”, “double”]
},
“min”: {
“required”: [“target”],
“supports”: [“integer”, “double”]
},
“percentile”: {
“required”: [“target”, “percentile”],
“supports”: [“integer”, “double”]
},
“select_unique”: {
“required”: [“target”],
“supports”: [“integer”, “double”, “string”]
},
“std_dev”: {
“required”: [“target”],
“supports”: [“integer”, “double”]
},
“sum”: {
“required”: [“target”],
“supports”: [“integer”, “double”]
},
“funnel”: {
“required”: [“segments”],
“supports”: [“string”]
},
“funnel”: {
“required”: [“targets”],
“supports”: [“integer”, “double”, “string”, “timestamp”]
}
}
گزارش قیف (Funnel)
هر قیف (funnel) ترکیبی از چند بخش است. هر بخش بر اساس بخش قبلی خود و actor اصلی آن بخش تشکیل می‌شود. به عنون مثال شما می‌خواهید مشخص کنید که چه تعدادی از کاربران از home page به product page، و بعد از آن به صفحه checkout رفته‌اند. در این مثال ما دو بخش داریم. در اولین بخش کاربرانی را که در استریم main ایونت view_home_page را دارند چک می‌شود، در مرحله بعد از بین آن ایونت‌ها، ایونت‌هایی که view_product_page از استریم product را دارند و هم‌زمان view_checkout_page را در استریم product دارند جدا می‌شوند. حال این بخش‌های جدا شده segment تلقی می‌شوند.
این مثال را می‌توانیم به این صورت مشاهده کنیم:
{
“key”: “1a2b3c”,
“project”: “PR17”,
“analysis”: {
“funnel”: {
“type”: “funnel”,
“segments”: [
{
“stream”: “main”,
“property”: “event_type”,
“steps”: [“view_home”]
},
{
“stream”: “product”,
“property”: “type_of_event_column”,
“steps”: [“view_product”, “checkout”]
}
]
}
},
“timezone”: “utc”,
“timeframe”: “this_2_weeks”
}
نتیجه این گزارش نیز به صورت زیر خواهد بود:
{
“key”: “1a2b3c”,
“group_set”: [],
“select_set”: [“view_home”, “view_product”, “checkout”],
“metric”: false,
“result”: [
{
“view_home”: 44,
“view_product”: 35,
“checkout”: 11
}
],
“time”: “2020-09-28T08:52:14Z”,
“timeframe”: {
“from”: “2019-09-30T20:30:00Z”,
“to”: “2020-09-28T05:22:14Z”
}
}
با استفاده از funnel اینگرو قادر خواهید بود گزارش‌های cohort و retention را ایجاد کنید
بهینه‌سازی گزارش‌ها
برای مشاهده سریع‌تر نتیجه گزارش‌ها پیشنهاد می‌کنیم این موارد را رعایت کنید:
– timeframe گزارش را تا آنجا که ممکن است کوچک در نظر بگیرید
– سایز event collection (استریم) ها را کاهش بدهید. تقریبا آنالیز 400M ایونت دو برابر 200M ایونت طول می‌کشد. اینگرو برای این طراحی شده است که بتوانید استریم‌های مختلفی را به آسانی و بدون نیاز به تغییرات خاصی ایجاد کنید. به این دلیل پیشنهاد می‌کنیم در هر بازه زمانی استریم خود را تغییر داده و سایز استریم‌های خود را کوچک کنید.
– تا آنجا که مقدور است داشبوردهای خود را زیاد کنید و از ایجاد داشبورد جامع خودداری کنید.
– از multi-analysis استفاده کنید.
– از group-by بجای ایجاد چند گزارش استفاده کنید.