تهیه حساب های کنترل شده توسط کاربر - راهنمای توسعه دهنده API

این سند مفاهیم مهمی را درباره استفاده از Provisioning API برای ایجاد حساب‌های Google Analytics جدید توضیح می‌دهد.

معرفی

Provisioning API می تواند برای ایجاد حساب های Google Analytics جدید و فعال کردن Google Analytics برای مشتریان شما در مقیاس استفاده شود. برای ارائه دهندگان خدمات واجد شرایط و شرکای بزرگ در نظر گرفته شده است. برای آشنایی با Provisioning API به نمای کلی Provisioning API مراجعه کنید.

قبل از اینکه شروع کنی

همه APIهای Google Analytics به روشی مشابه قابل دسترسی هستند. قبل از شروع با Provisioning API باید:

  • صفحه کتابخانه های سرویس گیرنده را برای لیست کاملی از کتابخانه های مشتری خاص زبان برنامه نویسی که با API کار می کنند، بخوانید.
  • راهنمای مرجع را بخوانید تا در مورد رابط API و نحوه دسترسی به داده‌ها بدون کتابخانه مشتری بیاموزید.

هر کتابخانه مشتری یک شیء سرویس تجزیه و تحلیل واحد را برای دسترسی به API فراهم می کند. برای ایجاد شیء سرویس معمولاً باید مراحل زیر را طی کنید:

  1. برنامه خود را در Google API Console ثبت کنید.
  2. مجوز ایجاد یک حساب Google Analytics جدید.
  3. یک شیء سرویس Analytics ایجاد کنید.

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

بررسی اجمالی

هنگام ایجاد حساب های Google Analytics با استفاده از Provisioning API، 2 جریان جداگانه وجود دارد که باید در نظر گرفته شود:

  • جریان فنی : جریان سرتاسری برای ارائه برنامه‌ای حساب Google Analytics برای یک کاربر.
  • جریان کاربر : ملاحظات پیاده سازی که باید برای جریان ایجاد حساب از دیدگاه کاربر انجام دهید.

این سند برای هر جریان مراحل و الزامات سطح بالا را شرح می دهد.

جریان فنی

مراحل سطح بالا برای استفاده از Provisioning API برای ایجاد یک حساب کاربری جدید و ادغام با Google Analytics عبارتند از:

  1. از کاربر بخواهید با استفاده از OAuth 2.0 برنامه/سرویس را احراز هویت و مجوز دهد .
  2. با استفاده از Provisioning API یک بلیط حساب ایجاد کنید .
  3. کاربر را هدایت کنید تا شرایط خدمات Google Analytics (TOS) را بپذیرد و پاسخ را مدیریت کند.
  4. (اختیاری) پیکربندی حساب و فرصت های یکپارچه سازی .

اگر تمام این مراحل با موفقیت انجام شود، یک حساب Google Analytics برای کاربر ایجاد می شود و شما شناسه حساب، شناسه ملک و شناسه نمایش (نمایه) حساب جدید را خواهید داشت.

برای هر مرحله زیر الزامات تکمیل مرحله، نتایج مرحله، و شرح جریان فنی برای مرحله وجود دارد.

1. احراز هویت و مجوز

هر کاربر باید برنامه شما را مجوز دهد و به آن امکان ارائه یک حساب Google Analytics از طرف خود را بدهد. جریان برنامه وب سرور OAuth 2.0 برای انجام این مرحله پیشنهاد می شود.

آنچه برای تکمیل این مرحله نیاز دارید

  • شناسه مشتری - Client ID پروژه ای که از آن استفاده خواهید کرد. این از کنسول توسعه دهندگان Google در دسترس است. برای اطلاعات بیشتر درباره جریان وب سرور OAuth 2.0 بخوانید.
  • Redirect URI - اینجا جایی است که کاربر به آن هدایت می شود و پاسخ OAuth 2.0 ارسال می شود.
    • Redirect URIs را پیکربندی کنید و Client ID پروژه خود را با استفاده از کنسول توسعه دهندگان Google دریافت کنید.
    • مقدار این پارامتر باید دقیقاً با یکی از مقادیر ثبت شده در Google Developers Console مطابقت داشته باشد (شامل طرح‌های http یا https، مورد، و دنباله '/').
  • Auth Scope for Google Analytics Provisioning API

نتیجه این مرحله

پس از تکمیل جریان OAuth 2.0، کاربر به درخواست شما اجازه می دهد تا از طرف او یک حساب ارائه دهد و شما یک رمز دسترسی برای کاربر خواهید داشت.

نکته در مورد توکن ها و محدوده ها:

  • اگر قصد دارید پس از ایجاد حساب، درخواست‌های بیشتری برای پیکربندی حساب کاربر یا داده‌های گزارش دهید، می‌توانید دامنه‌های اضافی را نیز در طول این مرحله مجاز کنید. به عنوان مثال، دامنه های readonly یا edit .
  • توکن های دسترسی طول عمر محدودی دارند. اگر برنامه شما نیاز به دسترسی به API Google Analytics بیش از طول عمر یک نشانه دسترسی دارد، می‌توانید با تنظیم access_type=offline یک توکن به‌روزرسانی درخواست کنید. یک Refresh Token باید در حافظه طولانی مدت امن برای هر کاربر ذخیره شود زیرا به برنامه شما اجازه می دهد تا توکن های دسترسی جدید را به دست آورد. برای جزئیات بیشتر به دسترسی آفلاین مراجعه کنید.

جریان فنی برای این مرحله

شما باید یک رمز دسترسی برای کاربر دریافت کنید. بر اساس جریانی که در وب سرور OAuth 2.0 توضیح داده شده است، کاربر را به سرویس Google Accounts ارسال کنید و پس از تکمیل جریان احراز هویت، وقتی کاربر به سرویس شما هدایت شد، پاسخ را مدیریت کنید.

URL OAuth 2.0 را برای بازدید کاربر تشکیل دهید

هنگامی که کاربر روی دکمه یا پیوندی برای شروع یا ایجاد یک حساب کلیک می کند، پیوند باید به شروع جریان OAuth 2.0 اشاره کند تا از کاربر بخواهد مجوزهای ارائه را بدهد. مثلا:

https://accounts.google.com/o/oauth2/auth?
  scope=https://www.googleapis.com/auth/analytics.provision
  &redirect_uri={YOUR REDIRECT URI for OAUTH}
  &response_type=code
  &client_id={YOUR CLIENT ID}
پاسخ را از سرویس حساب‌های Google مدیریت کنید

هنگامی که کاربر تصمیم خود را برای اعطای دسترسی به برنامه شما اتخاذ کرد، به redirect_uri همانطور که در URL ایجاد کرده‌اید با یک پارامتر پرس و جو حاوی کد مجوز هدایت می‌شود. اگر کاربر درخواست را تأیید کرد، می‌توان از پاسخ کد مجوز برای مبادله کد مجوز برای یک نشانه دسترسی با درخواست POST به API حساب‌های Google استفاده کرد.

ذخیره Refresh Token (در صورت وجود)

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

2. با استفاده از Provisioning API یک بلیط حساب ایجاد کنید

هنگامی که یک نشانه دسترسی برای کاربر مجاز دارید، می توانید از آن برای ایجاد یک درخواست به API Provisioning برای ایجاد یک بلیط حساب برای کاربر استفاده کنید. بلیط حساب اولین گام برای ایجاد یک حساب کاربری برای یک کاربر است.

آنچه برای تکمیل این مرحله نیاز دارید

یک نشانه دسترسی برای کاربر مجاز همانطور که در احراز هویت و مجوز و جزئیات تهیه زیر توضیح داده شده است:

  • تغییر مسیر URI
    • مشخص می کند که کاربر پس از صفحه شرایط خدمات Google Analytics (TOS) به کجا هدایت می شود. می تواند با URI تغییر مسیر مشخص شده در جریان مجوز OAuth 2.0 متفاوت باشد.
    • مقدار پارامتر Redirect URI باید دقیقاً با یکی از مقادیر ثبت شده در Google Developers Console مطابقت داشته باشد (شامل طرح‌های http یا https، مورد، و دنباله '/').
  • فیلدهای حساب
    • یک ویژگی name برای حساب مورد نیاز است.
  • فیلدهای ویژگی وب
    • یک ویژگی name برای ملک مورد نیاز است.
    • websiteUrl مورد نیاز است.
  • فیلدهای نمایه
    • یک ویژگی name برای نمایه مورد نیاز است.
    • یک timezone می تواند به صورت اختیاری ارائه شود. پیش فرض America/Los_Angeles است.

هنگام ایجاد یک بلیط حساب، فقط فیلدهای اصلی مشخص شده در بالا را می توان تنظیم کرد. پس از ایجاد حساب، هرگونه تغییر پیکربندی اضافی در ویژگی یا نمای (نمایه) را می توان با استفاده از مدیریت API انجام داد.

برای جزئیات بیشتر در مورد این فیلدها به مرجع API برای حساب‌ها ، ویژگی‌ها و نماها (نمایه‌ها) مراجعه کنید.

نتیجه این مرحله

پس از درخواست موفقیت آمیز به Provisioning API، یک بلیط حساب کوتاه مدت برای کاربر خواهید داشت. شناسه بلیط حساب در مرحله آخر استفاده می شود تا از کاربر خواسته شود شرایط خدمات (TOS) را بپذیرد و حساب خود را فعال کند. تا زمانی که TOS پذیرفته نشود، نمی توان از حساب کاربری استفاده کرد.

جریان فنی برای این مرحله

با استفاده از رمز دسترسی برای کاربر که در طی احراز هویت و مجوز به دست آمد، یک درخواست HTTP POST به API ارائه می شود.

ارائه درخواست API برای ایجاد بلیط حساب

برای جزئیات نحوه درخواست، روش createAccountTicket در مرجع Provisioning API مرور کنید.

پاسخ از Provisioning API

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

Account Ticket resource در مرجع Provisioning API برای جزئیات بیشتر در مورد پاسخ بررسی کنید.

پاسخ های خطا نیز باید توسط برنامه مدیریت شود.

3. کاربر شرایط خدمات Google Analytics (TOS) را می‌پذیرد

پس از اینکه یک شناسه بلیط حساب برای کاربر داشتید، می توانید از آن برای درخواست TOS استفاده کنید تا از کاربر بخواهد شرایط خدمات Google Analytics را بپذیرد.

آنچه برای تکمیل این مرحله نیاز دارید

شناسه بلیط حساب برای کاربر مجاز.

نتیجه این مرحله

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

جریان فنی برای این مرحله

با استفاده از شناسه بلیط حساب، کاربر را به صفحه Google Analytics TOS هدایت کنید تا بتواند TOS را بپذیرد، سپس باید پاسخ API را مدیریت کنید.

URL TOS را برای بازدید کاربر تشکیل دهید

کاربر را به صفحه TOS هدایت کنید و شناسه بلیط حساب را به عنوان بخشی از URL وارد کنید:

https://analytics.google.com/analytics/web/?provisioningSignup=false#/termsofservice/{account_ticket_id}
پاسخ TOS را مدیریت کنید

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

پاسخ‌های موفقیت‌آمیز داده‌های مربوط به ساختار حساب جدید ایجاد شده و همچنین accountTicketId اصلی را برمی‌گرداند:

https://{YOUR REDIRECT URI for TOS}?
  accountId={accountId}
  &webPropertyId={webPropertyId}
  &profileId={profileId}
  &accountTicketId={accountTicketId}

به عنوان مثال، اگر کنترل کننده TOS برای برنامه شما در http://www.your-app.com/gaTOS باشد، باید هنگام ایجاد بلیط های حساب، به عنوان redirectUri تنظیم شود. کنترل کننده TOS برنامه شما باید انتظار داشته باشد و به درستی درخواست های HTTP GET را که حاوی پارامترهای پرس و جو accountId ، webPropertyId ، profileId و accountTicketId هستند، برای مواردی که بلیط حساب معتبر است و کاربر TOS را پذیرفته است، بررسی کند.

پاسخ های ناموفق شامل پاسخ خطا خواهد بود:

https://{YOUR REDIRECT URI for TOS}?
  error={error_code}
  &accountTicketId={accountTicketId}

کنترل‌کننده TOS شما همچنین باید درخواست‌های HTTP GET را که حاوی پارامتر پرس و جوی error هستند، به درستی مدیریت کند که نشان می‌دهد مشکلی پیش آمده است. مقدار پارامتر query را می توان برای انجام اقدامات بیشتر یا نمایش یک پیام به کاربر استفاده کرد:

  • error=user_cancel - کاربر شرایط سرویس را نپذیرفت.
  • error=max_accounts_reached - کاربر به حد مجاز حساب Google Analytics رسیده است.
  • error=backend_error - یک خطای عمومی. سرور خطایی را برگرداند که در دسته های بالا نیست.

4. (اختیاری) فرصت های یکپارچه سازی

اگر جریان فنی بالا را دنبال کرده باشید، یک حساب کاربری برای کاربر ایجاد کرده اید و شناسه حساب، شناسه ملک و شناسه نمایه (نمایه) را خواهید داشت. اگر مجوزهای اضافی را نیز درخواست کردید، ممکن است یک نشانه به‌روزرسانی برای کاربر نیز داشته باشید. با این داده ها می توانید:

  • در صورت امکان، قطعه ردیابی استاندارد Google Analytics را با شناسه ویژگی حساب جدید ایجاد شده برای هر صفحه در وب سایت کاربر به طور خودکار تزریق کنید.
  • با استفاده از مدیریت API ، ویژگی کاربر را به صورت خودکار پیکربندی کنید.
  • با استفاده از Embed API یا Core Reporting API برای کاربر در محصول خود (به عنوان مثال در پنل مدیریت) گزارش هایی ارائه دهید.

جریان کاربر

این بخش ملاحظات پیاده سازی مربوط به مراحل جریان ایجاد حساب را از دیدگاه کاربر شرح می دهد.

جریان با ارائه 2 گزینه زیر توسط کاربر برای فعال کردن تجزیه و تحلیل برای دارایی خود شروع می شود:

  1. یک حساب Google Analytics ایجاد کنید
  2. از یک حساب Google Analytics موجود استفاده کنید. ( توجه : این جریان در این سند پوشش داده نمی‌شود. برای جزئیات نحوه دسترسی به داده‌های پیکربندی Google Analytics کاربر، به مدیریت API مراجعه کنید.)

هنگام ایجاد یک حساب Google Analytics جدید، اطلاعاتی وجود دارد که باید آنها را همراه با درخواست تامین ارسال کنید، مانند نام حساب، نام دارایی و غیره. بسته به اطلاعاتی که در مورد کاربر دارید و جریان ترجیحی که می‌خواهید نشان دهید آنها 3 گزینه اصلی برای شروع جریان کاربر پس از کلیک کاربر روی "ایجاد حساب کاربری" وجود دارد:

پس از مجوز، جزئیات حساب را بخواهید

در این حالت از کاربر در میانه فرآیند اطلاعات حساب خواسته می شود. جریان شبیه به موارد زیر خواهد بود:

  1. کاربر برای جریان OAuth 2.0 به سرویس حساب Google هدایت می شود. اگر کاربر یک حساب Google نداشته باشد یا وارد سیستم نشده باشد، از او خواسته می شود یک حساب Google ایجاد کند یا وارد سیستم شود.
  2. از کاربر خواسته می شود تا برنامه را برای "ایجاد حساب های Google Analytics" مجوز دهد.
  3. کاربر درخواست مجوز برای برنامه را می پذیرد.
  4. کاربر به ارائه دهنده خدمات هدایت می شود. توجه داشته باشید که اگر کاربر مجوز را رد کند، همچنان به ارائه دهنده خدمات هدایت می شود.
  5. فرمی به کاربر ارائه می شود تا جزئیات مربوط به حساب مورد نظر را برای ایجاد جمع آوری کند (مثلاً نام حساب، نام دارایی، نام نمایه، منطقه زمانی، URL وب سایت و غیره)
  6. کاربر فرم را پر و ارسال می کند و به Google هدایت می شود/شرایط خدمات Google Analytics (TOS) را نشان می دهد.
  7. کاربر TOS را می پذیرد.
  8. کاربر به ارائه دهنده خدمات هدایت می شود و پیام موفقیت آمیزی نشان می دهد که آنها با موفقیت یک حساب Google Analytics با جزئیات مربوط به حساب و نحوه دسترسی به آن ایجاد کرده اند. توجه داشته باشید که اگر کاربر TOS را نپذیرد، همچنان به ارائه‌دهنده خدمات هدایت می‌شود.

قبل از مجوز، جزئیات حساب را بخواهید

در این مورد، از کاربر برای جزئیات پیکربندی حسابی که قرار است ایجاد شود، خواسته می شود. جریان شبیه به موارد زیر خواهد بود:

  1. در سایت ارائه‌دهنده خدمات، فرمی به کاربر ارائه می‌شود تا جزئیات مربوط به حساب موردنظر را جمع‌آوری کند (به عنوان مثال نام حساب، نام دارایی، نام نمایه، منطقه زمانی، URL وب‌سایت).
  2. کاربر فرم را پر می کند، روی ارسال کلیک می کند و به سرویس حساب Google برای جریان OAuth 2.0 هدایت می شود. اگر کاربر یک حساب Google نداشته باشد یا وارد سیستم نشده باشد، از او خواسته می شود یک حساب Google ایجاد کند یا وارد سیستم شود.
  3. از کاربر خواسته می شود تا برنامه را برای "ایجاد حساب های Google Analytics" مجوز دهد.
  4. کاربر مجوزهای درخواستی برنامه را می پذیرد.
  5. کاربر به ارائه دهنده خدمات هدایت می شود.
  6. کاربر به Google هدایت می شود/شرایط خدمات Google Analytics (TOS) نشان داده می شود.
  7. کاربر TOS را می پذیرد.
  8. کاربر به ارائه دهنده خدمات هدایت می شود و پیام موفقیت آمیزی نشان می دهد که آنها با موفقیت یک حساب Google Analytics با جزئیات مربوط به حساب و نحوه دسترسی به آن ایجاد کرده اند.

جزئیات حساب را از قبل پر کنید یا از فرم ها رد شوید

اگر اطلاعات مربوط به حساب کاربری از قبل در دسترس باشد (به عنوان مثال URL وب سایت، نام وب سایت، منطقه زمانی، و غیره) هر دو گزینه بالا را می توان با موارد زیر ساده تر کرد:

  • فرم را از قبل پر کنید و به کاربر اجازه دهید در صورت تمایل ویرایش کند
  • رد شدن از مرحله فرم به طور کلی و ایجاد خودکار حساب با استفاده از اطلاعات موجود.