راهنمای یکپارچهسازی رضایت کوکی برای تحلیل محصول PostHog: کتاب بازی استقرار خود-میزبانی و ابری برای ۲۰۲۶
PostHog پلتفرمی است که تیمهای مهندسی هنگامی به آن روی میآورند که میخواهند تحلیل محصول، ضبط نشست، پرچمهای ویژگی، آزمایش، نظرسنجی و تحلیل وب را در یک پشته داشته باشند نه از پنج فروشنده مختلف. این ترکیب، پیشنهاد ارزشی است. به همین دلیل است که یک استقرار پیشفرض PostHog تعهدات رضایت متمرکزتری نسبت به تقریباً هر ابزار دیگری که یک ناشر نصب خواهد کرد، به همراه دارد. همان فراخوانی posthog.init() که رویدادهای محصول را ثبت میکند میتواند ضبط نشست را آغاز کند، پرچمهای ویژگی را در برابر شناسهای پایدار ارزیابی کند و برداشتهای نظرسنجی را در صف قرار دهد — و هر یک از این فعالیتها مبنای قانونی متفاوتی را تحت GDPR، ePrivacy و CCPA به کار میگیرد. خبر خوب این است که PostHog با یکی از دقیقترین APIهای رضایت در اکوسیستم تحلیل عرضه میشود؛ کار در واقع استفاده از آن است. این راهنما نحوه استقرار PostHog را توضیح میدهد تا موضع قانونی با واقعیت فنی در هر دو نصب خود-میزبانی و PostHog Cloud، در مناطق آمریکا و اروپا، و در سراسر سطح تحلیل، پخش مجدد، پرچمها و نظرسنجیها مطابقت داشته باشد.
چرا PostHog به رضایت نیاز دارد — و چرا پاسخ برای هر ماژول یکسان نیست
SDK وب PostHog یک برچسب صفحه منفعل نیست. در مقداردهی اولیه پیشفرض، SDK یک یا چند ورودی پایداری طرف اول تنظیم میکند — بهطور پیشفرض یک کوکی ترکیبی به علاوه طرح localStorage با کلید ph_{projectKey}_posthog — یک شناسه متمایز پایدار تولید میکند، بازدید اولیه صفحه را با مرجع، پارامترهای UTM و شناسههای کلیک ثبت میکند، و یک کانال رویداد طولانیمدت به هاست مصرف پیکربندیشده باز میکند. اگر ضبط نشست در سطح پروژه فعال باشد، SDK علاوه بر این شروع به پخش جریانی از DOM رندرشده، مختصات ماوس و رویدادهای ورودی میکند. اگر پرچمهای ویژگی پیکربندی شده باشند، SDK آنها را در برابر شناسه متمایز ارزیابی میکند، تصمیمات را برای نشست ذخیره میکند و برای هر ارزیابی یک رویداد $feature_flag_called ارسال میکند.
هر یک از این فعالیتها به یک دروازه رضایت متفاوت مربوط میشود. حفظ یک شناسه متمایز طبق ماده 5(3) دستورالعمل ePrivacy یک عملیات ذخیرهسازی و دسترسی است و نیاز به رضایت قبلی، آزادانه دادهشده، خاص، آگاهانه و صریح در سراسر EEA، UK و هر حوزه قضایی که همان استاندارد را اتخاذ کرده دارد. ثبت رویدادهای رفتاری طبق GDPR پردازش دادههای شخصی است زیرا ترکیب شناسه، آدرس IP و ردپای رفتاری برای شناسایی یک فرد کافی است. ضبط نشست طبق راهنمای ضبط-نشست EDPB در یک دسته جداگانه و سختگیرانهتر قرار دارد — ضبط مجدد، DOM رندرشده و هر فیلد ورودی بدون ماسک را ثبت میکند و نیاز به رضایت صریح و دقیق دارد که از رضایت عمومی تحلیل متمایز باشد. ارزیابی پرچم ویژگی ظریفترین است: یک بررسی پرچم که یک بولین برمیگرداند به خودی خود نیاز به رضایت ندارد، اما حفظ تخصیص پرچم کاربر در یک شناسه پایدار در سراسر نشستها نیاز دارد، زیرا اینگونه است که آزمایش مبتنی بر پرچم، دادههای قابل ردیابی سطح کاربر ایجاد میکند.
آنچه PostHog قبل از رضایت مینویسد — و چه چیزی باید سرکوب شود
SDK مرورگر پیشفرض PostHog موارد زیر را در مقداردهی اولیه مینویسد: یک کوکی ترکیبی و ورودی localStorage زیر ph_{projectKey}_posthog که شامل شناسه متمایز، شناسه نشست و تصمیمات پرچم ویژگی است، به علاوه در صورت فعال بودن ضبط نشست، یک بافر ضبط درونحافظهای اضافی که هر چند ثانیه به نقطه پایانی مصرف فلاش میشود. SDK همچنین یک رویداد فوری $pageview و در صورت فعال بودن ثبت خودکار، هر کلیک، تعامل فرم و کلیک خشم بعدی در صفحه را ارسال میکند.
الگوی توصیهشده این است که PostHog را با opt_out_capturing_by_default: true و disable_session_recording: true مقداردهی اولیه کنید، سپس هر دو پرچم را پس از دریافت سیگنال مثبت از배너رضایت تغییر دهید. این موضع یکپارچهسازی است که مستندات PostHog اکنون توصیه میکند، و موضعی است که بررسی تنظیمکننده را پشت سر میگذارد زیرا پیشفرض را معکوس میکند: هیچچیز تا زمانی که رضایت ثبت نشده ثبت نمیشود، و SDK یک انتقال پاک به جای یک بازتنظیم حالتدار ارائه میدهد.
کوکیها، ورودیهای localStorage و شناسههایی که PostHog ذخیره میکند
Browser SDK 1.x یک ورودی پایداری به ازای هر پروژه مینویسد، با کلید ph_{projectKey}_posthog، با انقضای ۳۶۵ روزه بهطور پیشفرض. گزینه مقداردهی اولیه persistence مکانیزم زیربنایی را کنترل میکند: فقط cookie، فقط localStorage، localStorage+cookie (پیشفرض)، sessionStorage، یا memory. برای استقرار رضایت-اول، پایداری memory پیشفرض صحیح است هنگامی که هنوز رضایت اعطا نشده — تضمین میکند که هیچ شناسهای از نشست صفحه عمر بیشتری ندارد — با انتقال به localStorage+cookie پس از تغییر رضایت. SDK همچنین یک نشانگر opt-in یا opt-out زیر __ph_opt_in_out_{projectKey} مینویسد تا انتخاب کاربر را در سراسر بازدیدها به یاد بیاورد؛ آن نشانگر خود یک کوکی ضروری است زیرا یک تصمیم رضایت را ذخیره میکند.
نگاشت ماژولهای PostHog به چارچوبهای رضایت
PostHog بهطور بومی IAB TCF یا پلتفرم حریم خصوصی جهانی IAB را پیادهسازی نمیکند، و به عنوان یک فروشنده فناوری تبلیغات ساخته نشده است. با این حال، از طریق پلزنی سمت ناشر با Google Consent Mode v2 ادغام میشود، یک API opt-in و opt-out بومی را نمایان میکند، و از هدر Do Not Track از طریق گزینه مقداردهی اولیه respect_dnt احترام میگذارد. الگویی که در تولید کار میکند هر ماژول PostHog را به عنوان یک دروازه جداگانه مرتبط با یک سیگنال CMP خاص میداند.
- رویدادهای تحلیل محصول به هدف تحلیل متصل میشوند. از نظر TCF این معمولاً هدف ۸ (اندازهگیری عملکرد محتوا) همراه با هدف ۱ (ذخیره و/یا دسترسی به اطلاعات) است. برای Consent Mode این به analytics_storage نگاشت میشود.
- ضبط نشست پشت یک دروازه سختگیرانهتر قرار دارد. ضبط نشست PostHog DOM رندرشده و هر فیلد ورودی بدون ماسک را ثبت میکند، بنابراین یک opt-in سطح اولویت یا تحقیق متمایز از تحلیل تحت راهنمایی EDPB موضع قابل دفاع است.
- پرچمهای ویژگی و آزمایش میتوانند با ارزیابی موقت و درونحافظهای تحت پایه منافع مشروع اجرا شوند وقتی هدف فقط تغییر صفحه رندرشده است. تخصیص پرچم پایدار متصل به یک شناسه پایدار در سراسر نشستها به همان رضایت تحلیل نیاز دارد، زیرا در این حالت است که پرچم تبدیل به یک نقطه داده قابل ردیابی سطح کاربر میشود.
- نظرسنجیها و بازخورد به همان دروازه ضبط نشست متصل میشوند وقتی ورودی آزاد متن جمعآوری میکنند، یا به دروازه تحلیل وقتی فقط امتیازها یا پاسخهای تکانتخابی جمعآوری میکنند.
الگوی یکپارچهسازی که کار میکند
استقرار مرجع چهار بخش دارد: یک CMP که یک رویداد تغییر رضایت بلادرنگ را نمایان میکند، یک بوتاسترپ معوق که PostHog را با ثبت و پخش مجدد غیرفعال مقداردهی اولیه میکند، یک شنونده رضایت که opt_in_capturing و کلید ضبط را هنگام باز شدن دروازههای مرتبط تغییر میدهد، و یک مسیر خروج که opt_out_capturing را فراخوانی میکند، بافر پخش مجدد را متوقف میکند و شناسههای پایدار را از طریق API ریست SDK پاک میکند.
پیادهسازی وب
پاکترین الگو این است که SDK PostHog را در هر صفحه بارگذاری کنید اما posthog.init(apiKey, { api_host: 'https://eu.posthog.com', opt_out_capturing_by_default: true, disable_session_recording: true, persistence: 'memory', respect_dnt: true }) را به عنوان بوتاسترپ اولیه فراخوانی کنید. در رویداد تغییر رضایت CMP مشترک شوید. وقتی دسته تحلیل به درست تبدیل میشود، posthog.set_config({ persistence: 'localStorage+cookie' }) را فراخوانی کنید و بعد posthog.opt_in_capturing()؛ این ثبت رویداد را مجدداً فعال میکند و انتقال پایداری شروع به نوشتن شناسه متمایز میکند. وقتی دسته ضبط-نشست به درست تبدیل میشود، posthog.startSessionRecording() را فراخوانی کنید. وقتی هر دروازهای پس گرفته میشود، posthog.opt_out_capturing() برای دروازه تحلیل یا posthog.stopSessionRecording() برای دروازه پخش مجدد فراخوانی کنید، ورودیهای پایداری مرتبط را از طریق posthog.reset() منقضی کنید، و یک درخواست حذف از طریق GDPR API PostHog ارسال کنید اگر کاربر حق پاکسازی خود را اعمال کرده است.
انتخاب منطقه: PostHog Cloud آمریکا در مقابل اروپا در مقابل خود-میزبانی
PostHog دو منطقه ابری دارد — آمریکا (us.posthog.com) و اروپا (eu.posthog.com) — و از نصبهای خود-میزبانی در زیرساخت خود مشتری پشتیبانی میکند. برای ترافیک EEA و UK، ابر اروپایی پیشفرض مناسب است؛ مصرف، پردازش و ذخیرهسازی را در داخل EEA نگه میدارد و مواجهه Schrems II که هر استقرار تحلیل منطقه آمریکا دارد را کاهش میدهد. گزینه مقداردهی اولیه api_host منطقه را مشخص میکند. PostHog خود-میزبانی کل پشته را به زیرساخت خود ناشر منتقل میکند که قویترین موضع اقامت داده است اما تعهدات رضایت را حذف نمیکند — پایه قانونی داده را دنبال میکند نه اپراتور را. هر گزینهای که انتخاب شود باید در اطلاعیه حریم خصوصی و دفتر ثبت پردازش کنترلر منعکس شود.
ثبت سمت سرور
PostHog از مصرف رویداد سمت سرور از طریق SDKهای Python، Node، Go، Ruby و PHP پشتیبانی میکند. رویدادهای سمت سرور از رضایت معاف نیستند — پایه قانونی داده را دنبال میکند — اما مصرف سمت سرور به ناشر کنترل کامل بر اینکه چه فیلدهایی ارسال میشوند و چه زمانی میدهد. یک الگوی رایج این است که یک مجموعه رویداد اولیه حداقلی را سمت سرور تحت منافع مشروع ثبت کنید، سپس آن رویدادها را با جزئیات رفتاری از کلاینت فقط پس از اینکه کاربر رضایت تحلیل داده غنی کنید. رویدادهای سمت سرور و سمت کلاینت روی همان شناسه متمایز پیوند میخورند وقتی رضایت تغییر کرده؛ قبل از رضایت، رویدادهای سمت سرور با یک شناسه ناشناس و موقت که در هر نشست ریست میشود ارسال میشوند.
اعتبارسنجی یکپارچهسازی و مسیر حسابرسی
مرحله اعتبارسنجی همان چیزی است که تنظیمکنندهها بررسی میکنند و ناشران اغلب از آن میگذرند. یک استقرار PostHog به درستی یکپارچهشده باید چهار آزمون را به ترتیب پشت سر بگذارد. اول، یک نشست مرورگر پاک با배너نشاندادهشده اما هیچ انتخابی نشده باید صفر درخواست به api_host پیکربندیشده فراتر از دریافت فایل SDK، صفر کوکی ph_ در document.cookie، و صفر ورودی ph_ در localStorage تولید کند. دوم، رد کردن تحلیل باید آن حالت را حفظ کند — بدون ثبت، بدون ضبط، بدون شناسه پایدار. سوم، قبول کردن تحلیل باید یک رویداد فوری $opt_in، ورودی پایداری مورد انتظار ph_{projectKey}_posthog با ویژگیهای SameSite صحیح، و ترافیک رویداد جاری به هاست پیکربندیشده تولید کند. چهارم، پس گرفتن رضایت بعد از واقعیت باید فوراً ثبت و پخش مجدد بیشتر را متوقف کند، شناسههای پایدار را منقضی کند، و یک درخواست حذف از طریق GDPR API PostHog فعال کند اگر کاربر پاکسازی را اعمال کرده است.
انتظار مسیر حسابرسی تحت دستورالعملهای배너کوکی ۲۰۲۳ EDPB و اولویتهای نوسازیشده گروه کاری ۲۰۲۶ این است که ناشر میتواند برای هر رویدادی در پروژه PostHog ثابت کند که کاربری که آن را تولید کرده در لحظه ثبت رضایت معتبر داده بوده است. الگوی استاندارد این است که نسخه رضایت و زمانمهر را به عنوان ویژگیهای شخص در شناسه متمایز از طریق posthog.setPersonProperties({ consent_version: 'v3', consent_ts: ts }) تنظیم کنید تا هر رویداد فردی به یک ورودی خاص گزارش رضایت قابل ردیابی باشد. یک استقرار به درستی دروازهبندیشده، همراه با انتخاب منطقهای که با مخاطبان مطابقت دارد، پایداری که به صورت پیشفرض حافظه است، و یک مسیر حذف که با پسگرفتن فعال میشود، PostHog را از یک ریسک تمرکز نظارتی به یک مرکز قابل دفاع از پشته تحلیل محصول تبدیل میکند.