توفير الحسابات التي يتحكم فيها المستخدم - دليل مطوِّري واجهة برمجة التطبيقات

يشرح هذا المستند مفاهيم مهمة حول استخدام واجهة برمجة التطبيقات "إدارة الحسابات" لإنشاء حسابات جديدة على "إحصاءات Google".

مقدمة

يمكن استخدام واجهة برمجة التطبيقات لإدارة الحسابات لإنشاء حسابات جديدة على "إحصاءات Google" وتفعيل "إحصاءات Google" لعملائك على نطاق واسع. هذا البرنامج مخصّص لمقدّمي الخدمات المؤهلين والشركاء الكبار. يُرجى الانتقال إلى نظرة عامة على واجهة برمجة التطبيقات لإدارة الحسابات للاطلاع على مقدمة عن واجهة برمجة التطبيقات لإدارة الحسابات.

قبل البدء

يتم الوصول إلى جميع واجهات برمجة تطبيقات "إحصاءات Google" بطريقة مشابهة. قبل بدء استخدام واجهة برمجة التطبيقات لإدارة الحسابات، عليك إجراء ما يلي:

  • يمكنك الاطّلاع على صفحة مكتبات العملاء للحصول على قائمة كاملة بمكتبات العملاء الخاصة بلغة البرمجة التي تعمل مع واجهة برمجة التطبيقات.
  • اقرأ الدليل المرجعي للتعرّف على واجهة برمجة التطبيقات وكيفية الوصول إلى البيانات بدون مكتبة برامج.

توفر كل مكتبة عملاء عنصر خدمة تحليل بيانات واحدًا للوصول إلى واجهة برمجة التطبيقات لإدارة الحسابات. لإنشاء عنصر الخدمة، يجب اتّباع الخطوات التالية بشكل عام:

  1. سجِّل تطبيقك في وحدة التحكم في واجهة Google API.
  2. منح الإذن لإنشاء حساب جديد على "إحصاءات Google"
  3. أنشئ عنصر خدمة على "إحصاءات Google".

في حال عدم إكمالك لهذه الخطوات، يُرجى التوقف عن قراءة البرنامج التعليمي المخصّص لواجهة برمجة تطبيقات Google Analytics API. يرشدك هذا الدليل التعليمي خلال الخطوات الأولية لإنشاء تطبيق واجهة برمجة التطبيقات Google Analytics API. وبعد اكتمالها، ستفهم كيفية الوصول إلى واجهات برمجة تطبيقات "إحصاءات Google" لتنفيذ مهام عملية.

نظرة عامة

عند إنشاء حسابات "إحصاءات Google" باستخدام واجهة برمجة التطبيقات لإدارة الحسابات، هناك مساران منفصلان يجب أخذهما في الاعتبار:

  • التدفق الفني: المسار الشامل لتوفير حساب على "إحصاءات Google" آليًا للمستخدم.
  • تدفق المستخدم: اعتبارات التنفيذ التي يجب وضعها في عملية إنشاء الحساب من منظور المستخدم.

يوضّح هذا المستند الخطوات والمتطلبات العالية المستوى لكل مسار.

التدفق الفني

الخطوات عالية المستوى لاستخدام واجهة برمجة التطبيقات لإدارة الحسابات من أجل إنشاء حساب جديد ودمجه مع "إحصاءات Google" هي:

  1. اطلب من المستخدم المصادقة والتفويض للتطبيق/الخدمة باستخدام OAuth 2.0.
  2. إنشاء طلب دعم حساب باستخدام واجهة برمجة التطبيقات Administration Service (واجهة برمجة التطبيقات لإدارة الحسابات).
  3. عليك إعادة توجيه المستخدم إلى قبول بنود خدمة "إحصاءات Google" والتعامل مع الردّ.
  4. (اختياري) اضبط الحساب و فرص الدمج.

في حال إكمال جميع هذه الخطوات بنجاح، سيتم إنشاء حساب على "إحصاءات Google" للمستخدم، وسيكون لديك رقم تعريف الحساب ورقم تعريف الموقع ورقم تعريف الملف الشخصي للحساب الجديد.

لكل خطوة أدناه متطلبات لإكمال الخطوة ونتائج للخطوة ووصف للتدفق الفني للخطوة.

1- المصادقة والترخيص

يحتاج كل مستخدم إلى تفويض تطبيقك ومنحه إمكانية إدارة حساب على "إحصاءات Google" نيابةً عنه. يتم اقتراح خادم ويب OAuth 2.0 لتنفيذ هذه الخطوة.

ما تحتاج إليه لإكمال هذه الخطوة

نتيجة هذه الخطوة

بعد اكتمال تدفق OAuth 2.0، سيكون المستخدم قد فوّض طلبك بتوفير حساب نيابةً عنه وستحصل على رمز دخول للمستخدم.

ملاحظة حول الرموز المميّزة والنطاقات:

  • إذا كنت تنوي تقديم طلبات إضافية بشأن بيانات إعداد حساب المستخدم أو إعداد التقارير له بعد إنشاء الحساب، يمكنك أيضًا تفويض نطاقات إضافية خلال هذه الخطوة. على سبيل المثال، النطاقان readonly أو edit.
  • رموز الدخول لها فترات زمنية محدودة. إذا كان تطبيقك يحتاج إلى الوصول إلى واجهة برمجة تطبيقات "إحصاءات Google" بعد انتهاء صلاحية رمز دخول واحد، يمكنك أيضًا طلب الرمز المميّز لإعادة التحميل عن طريق ضبط access_type=offline. يجب حفظ الرمز المميّز لإعادة التحميل في مساحة تخزين آمنة طويلة الأجل لكل مستخدم، لأنّه يسمح لتطبيقك بالحصول على رموز دخول جديدة. راجِع العمل بلا إنترنت للحصول على مزيد من التفاصيل.

الخطوات التقنية لهذه الخطوة

يجب الحصول على رمز دخول للمستخدم. استنادًا إلى التدفق الموضح في خادم OAuth 2.0 على الويب، يمكنك إرسال المستخدم إلى خدمة حسابات Google، ثم معالجة الاستجابة عندما تتم إعادة توجيه المستخدم إلى خدمتك بعد إكمال تدفق المصادقة.

نموذج عنوان 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 إلى واجهة برمجة تطبيقات حسابات Google.

احفظ الرمز المميّز لإعادة التحميل (إن وُجد).

سيتم استخدام رمز الدخول في الخطوة التالية لتتمكن من تخزينه مؤقتًا. إذا طلبت أيضًا رمزًا مميزًا للتحديث، يجب تخزين هذا الرمز بشكل آمن للاستخدام على المدى الطويل. يدوم الرمز المميّز للتحديث ويمكن استخدامه لإصدار رموز دخول جديدة.

2. إنشاء طلب دعم حساب باستخدام واجهة برمجة التطبيقات لإدارة الحسابات

بعد حصولك على رمز دخول للمستخدم المفوَّض، يمكنك استخدامه لتقديم طلب إلى واجهة برمجة التطبيقات لإدارة الحسابات من أجل إنشاء "بطاقة حساب" للمستخدم. تذكرة الحساب هي الخطوة الأولى لإنشاء حساب للمستخدم.

ما تحتاج إليه لإكمال هذه الخطوة

رمز الدخول للمستخدم المصرح له كما هو موضح في المصادقة والتفويض وتفاصيل إدارة الحسابات التالية:

  • معرّف الموارد المنتظم (URI) لإعادة التوجيه
    • تحدّد هذه السياسة المكان الذي تتم إعادة توجيه المستخدِم إليه بعد صفحة بنود خدمة "إحصاءات Google". ويمكن أن يختلف عن معرّف الموارد المنتظم (URI) لإعادة التوجيه المحدّد أثناء تدفق تفويض OAuth 2.0.
    • يجب أن تتطابق قيمة معلَمة معرّف الموارد المنتظم (URI) لإعادة التوجيه تمامًا مع إحدى القيم المسجّلة في Google Developers Console (بما في ذلك المخططات http أو https، وحالة الأحرف، ولاحقة '/').
  • حقول الحساب
    • يجب إضافة السمة name مطلوبة للحساب.
  • حقول الموقع الإلكتروني
    • يجب إضافة السمة name مطلوبة للموقع الإلكتروني.
    • يجب إدخال websiteUrl مطلوب.
  • حقول الملف الشخصي
    • يجب إضافة السمة name مطلوبة للملف الشخصي.
    • يمكن تقديم timezone بشكل اختياري. القيمة التلقائية America/Los_Angeles.

عند إنشاء تذكرة حساب، لا يمكن تعيين سوى الحقول الأساسية المحددة أعلاه. بعد إنشاء الحساب، يمكن إجراء أيّ تغييرات إضافية على إعدادات الموقع أو الملف الشخصي باستخدام Management API.

اطّلع على مرجع واجهة برمجة التطبيقات لكل من الحسابات والمواقع والملفات الشخصية (الملفات الشخصية) للحصول على تفاصيل إضافية حول هذه الحقول.

نتيجة هذه الخطوة

بعد تقديم طلب ناجح إلى واجهة برمجة التطبيقات لإدارة الحسابات، سيكون لديك تذكرة حساب قصيرة الأجل للمستخدم. يتم استخدام رقم تعريف تذكرة الحساب في الخطوة الأخيرة لمطالبة المستخدم بقبول بنود الخدمة وتفعيل حسابه. لا يمكن استخدام الحساب إلا بعد قبول بنود الخدمة.

الخطوات التقنية لهذه الخطوة

باستخدام رمز الدخول للمستخدم الذي تم الحصول عليه أثناء المصادقة والتفويض، يتم إجراء طلب HTTP POST إلى واجهة برمجة التطبيقات لإدارة الحسابات.

لإدارة طلب بيانات من واجهة برمجة التطبيقات لإنشاء تذكرة الحساب

يمكنك مراجعة طريقة createAccountTicket في مرجع واجهة برمجة التطبيقات لإدارة الحسابات لمعرفة تفاصيل حول كيفية تقديم الطلب.

رد من واجهة برمجة التطبيقات لإدارة الحسابات

يعرض الطلب الناجح استجابة 200. يحتوي نص الاستجابة على تذكرة الحساب، وهي قصيرة الأجل. تتكون تذكرة الحساب من معرّف وتفاصيل العرض التدرّجي للحساب الجديد.

راجع Account Ticket resource في مرجع واجهة برمجة التطبيقات لإدارة الحسابات للحصول على تفاصيل حول الرد.

يجب أيضًا أن يعالج التطبيق ردود الأخطاء.

3- يوافق المستخدم على بنود خدمة "إحصاءات Google" (بنود الخدمة)

بعد حصولك على رقم تعريف تذكرة الحساب للمستخدم، يمكنك استخدامه مع طلب بنود الخدمة لمطالبة المستخدم بقبول بنود خدمة "إحصاءات Google".

ما تحتاج إليه لإكمال هذه الخطوة

رقم تعريف تذكرة الحساب للمستخدم المفوّض.

نتيجة هذه الخطوة

بعد إكمال مسار بنود الخدمة بنجاح باستخدام رقم تعريف تذكرة الحساب، سيتم إنشاء الحساب والموقع والملف الشخصي (الملف الشخصي). سيكون لدى المستخدم الآن حساب نشط. وسيتضمّن الردّ من صفحة "بنود الخدمة" رقم تعريف الحساب ورقم تعريف الموقع ورقم تعريف الملف الشخصي (الملف الشخصي).

الخطوات التقنية لهذه الخطوة

باستخدام رقم تعريف تذكرة الحساب، أعِد توجيه المستخدم إلى صفحة بنود خدمة "إحصاءات Google" التي يمكنه فيها قبول بنود الخدمة، وبعد ذلك سيكون عليك معالجة الردّ من واجهة برمجة التطبيقات.

إنشاء عنوان URL لبنود الخدمة ليتمكّن المستخدم من الانتقال إليه

إعادة توجيه المستخدم إلى صفحة "بنود الخدمة" وتضمين رقم تعريف تذكرة الحساب كجزء من عنوان URL:

https://analytics.google.com/analytics/web/?provisioningSignup=false#/termsofservice/{account_ticket_id}
التعامل مع الرد على بنود الخدمة

بعد أن يتّخذ المستخدم إجراءً على صفحة "بنود الخدمة"، ستتم إعادة توجيهه مرة أخرى إلى redirectUri التي تم تحديدها أثناء إنشاء طلب دعم الحساب. وسيتم تضمين الرد من صفحة "بنود الخدمة" كجزء من سلسلة طلب البحث.

ستعرض الردود الناجحة بيانات حول بنية الحساب التي تم إنشاؤها حديثًا بالإضافة إلى بنية accountTicketId الأصلية:

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

على سبيل المثال، إذا كان معالج بنود الخدمة لتطبيقك في http://www.your-app.com/gaTOS، يجب ضبطه على أنّه redirectUri عند إنشاء تذاكر الحساب. يجب أن يتوقع معالج بنود خدمة التطبيق طلبات HTTP GET التي تحتوي على accountId وwebPropertyId وprofileId وaccountTicketId معلَمات طلب البحث ويعالجها بشكل صحيح في الحالات التي تكون فيها تذكرة الحساب صالحة ووافق المستخدم على بنود الخدمة.

ستتضمّن الردود غير الناجحة استجابة الخطأ:

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

على معالج بنود الخدمة أيضًا التعامل بشكل صحيح مع طلبات HTTP GET التي تحتوي على معلَمة طلب البحث error، ما يشير إلى حدوث خطأ. يمكن استخدام قيمة معلَمة طلب البحث لاتخاذ إجراء إضافي أو عرض رسالة للمستخدم:

  • error=user_cancel - لم يقبل المستخدم بنود الخدمة.
  • error=max_accounts_reached - وصل المستخدِم إلى الحدّ الأقصى المسموح به لحسابات "إحصاءات Google".
  • error=backend_error - خطأ عام. عرض الخادم خطأ ليس ضمن الفئات أعلاه.

4. (اختياري) فرص الدمج

إذا اتّبعت الخطوات الفنية أعلاه، ستكون قد أنشأت حسابًا للمستخدم وستحصل على رقم تعريف الحساب ورقم تعريف الموقع ورقم تعريف الملف الشخصي (الملف الشخصي). إذا طلبت أيضًا أذونات إضافية، قد يكون لديك أيضًا رمز مميز لإعادة التحميل للمستخدم. باستخدام هذه البيانات، يمكنك إجراء ما يلي:

تدفق المستخدم

يصف هذا القسم اعتبارات التنفيذ المتعلقة بخطوات عملية إنشاء الحساب من منظور المستخدم.

يبدأ المسار مع تقديم المستخدم الخيارَين التاليَين لتفعيل الإحصاءات لموقعه:

  1. إنشاء حساب على "إحصاءات Google"
  2. استخدام حساب حالي في "إحصاءات Google" (ملاحظة: لم يتناول هذا المستند هذا المسار. اطّلِع على Management API لمعرفة تفاصيل عن كيفية الوصول إلى بيانات ضبط "إحصاءات Google" لمستخدم معيَّن).

عند إنشاء حساب جديد على "إحصاءات Google"، هناك معلومات مطلوبة لإرسالها مع طلب توفير المتطلبات اللازمة مثل اسم الحساب واسم الموقع وما إلى ذلك. واستنادًا إلى المعلومات المتوفرة لديك عن المستخدم والتدفق المفضّل الذي تريد أن تعرض له 3 خيارات رئيسية لبدء تدفق المستخدم بعد نقر المستخدم على "إنشاء الحساب":

طلب الحصول على تفاصيل الحساب بعد منح الإذن

في هذه الحالة، يُطلب من المستخدم تقديم تفاصيل الحساب في منتصف العملية. سيبدو التدفق مشابهًا لما يلي:

  1. تتم إعادة توجيه المستخدم إلى خدمة حساب Google لمسار OAuth 2.0. إذا لم يكن لدى المستخدم حساب Google أو لم يسجّل الدخول، سيُطلب منه إنشاء حساب Google أو تسجيل الدخول.
  2. يُطلب من المستخدم السماح للتطبيق بـ "إنشاء حسابات على إحصاءات Google".
  3. يقبل المستخدم طلب الأذونات للتطبيق.
  4. تتم إعادة توجيه المستخدم إلى "مقدِّم الخدمة". يُرجى ملاحظة أنّه إذا رفض المستخدم الإذن، ستتم إعادة توجيهه إلى مقدِّم الخدمة مرة أخرى.
  5. يتم تقديم نموذج للمستخدم لجمع تفاصيل عن الحساب الذي سيتم إنشاؤه (مثل اسم الحساب واسم الموقع الإلكتروني واسم الملف الشخصي والمنطقة الزمنية وعنوان URL للموقع الإلكتروني وما إلى ذلك).
  6. يملأ المستخدم النموذج ويرسله وتتم إعادة توجيهه إلى Google/يظهر لبنود خدمة "إحصاءات Google".
  7. قبول المستخدم لبنود الخدمة.
  8. تتمّ إعادة توجيه المستخدِم إلى مقدّم الخدمة وتظهر له رسالة نجاح تفيد بأنّه أنشأ حسابًا على "إحصاءات Google" بنجاح يتضمّن تفاصيل عن الحساب وكيفية الوصول إليه. تجدر الإشارة إلى أنّه في حال عدم قبول المستخدم لبنود الخدمة، ستتم إعادة توجيهه إلى مقدِّم الخدمة مرة أخرى.

طلب تفاصيل الحساب قبل منح الإذن

في هذه الحالة، يُطلب من المستخدم مقدمًا تفاصيل الإعداد للحساب الذي سيتم إنشاؤه. سيبدو التدفق مشابهًا لما يلي:

  1. على الموقع الإلكتروني لمقدّم الخدمة، يتم عرض نموذج للمستخدم لجمع تفاصيل عن الحساب الذي سيتم إنشاؤه (مثل اسم الحساب واسم الموقع الإلكتروني واسم الملف الشخصي والمنطقة الزمنية وعنوان URL للموقع الإلكتروني).
  2. يملأ المستخدم النموذج وينقر على "إرسال" ثم يُعاد توجيهه إلى خدمة حساب Google لتدفق OAuth 2.0. إذا لم يكن المستخدم لديه حساب Google أو لم يسجّل الدخول، سيُطلب منه إنشاء حساب Google أو تسجيل الدخول.
  3. يُطلب من المستخدم السماح للتطبيق بـ "إنشاء حسابات على إحصاءات Google".
  4. يقبل المستخدم الأذونات المطلوبة للتطبيق.
  5. تتم إعادة توجيه المستخدم إلى "مقدِّم الخدمة".
  6. تتم إعادة توجيه المستخدم إلى Google/عرض بنود خدمة "إحصاءات Google" (TOS).
  7. قبول المستخدم لبنود الخدمة.
  8. تتمّ إعادة توجيه المستخدِم إلى مقدّم الخدمة وتظهر له رسالة نجاح تفيد بأنّه أنشأ حسابًا على "إحصاءات Google" بنجاح يتضمّن تفاصيل عن الحساب وكيفية الوصول إليه.

ملء تفاصيل الحساب مسبقًا أو تخطّي النماذج

في حال توفُّر معلومات حول حساب المستخدم (مثل عنوان URL للموقع الإلكتروني واسم الموقع الإلكتروني والمنطقة الزمنية وما إلى ذلك)، يمكن عندئذٍ تبسيط كلا الخيارين أعلاه من خلال:

  • ملء النموذج مسبقًا والسماح للمستخدم بالتعديل إذا أراد
  • تخطي خطوة النموذج تمامًا وإنشاء الحساب تلقائيًا باستخدام المعلومات الحالية.