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

تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.

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

المقدمة

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

قبل البدء

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

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

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

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

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

نظرة عامة

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

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

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

التدفق الفني

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

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

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

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

1- المصادقة والتفويض

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

الإجراءات المطلوبة لإكمال هذه الخطوة

  • Client ID (رقم تعريف العميل) - رقم Client ID للمشروع الذي ستستخدمه. يتوفّر ذلك من Google Developers Console. يمكنك الاطّلاع على المزيد من المعلومات حول مسار خادم الويب OAuth 2.0 لمعرفة المزيد من المعلومات.
  • معرّف الموارد المنتظم (URI) لإعادة التوجيه: هذا هو المكان الذي تتم إعادة توجيه المستخدم إليه ويتم إرسال استجابة OAuth 2.0.
    • يمكنك إعداد Redirect URIs والحصول على Client ID لمشروعك باستخدام Google Developers Console.
    • ويجب أن تتطابق قيمة هذه المعلَمة تمامًا مع إحدى القيم المسجّلة في Google Developers Console (بما في ذلك مخططات http أو https والحالة واللاحقة '/').
  • نطاق المصادقة لواجهة برمجة التطبيقات لإدارة حسابات "إحصاءات Google"

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

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

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

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

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

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

إتاحة عنوان URL من أجل الإصدار 2.0 من بروتوكول OAuth للمستخدم

عندما ينقر المستخدم على زر أو رابط للبدء أو إنشاء حساب، يجب أن يشير الرابط إلى بداية تدفق 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 Accounts API.

حفظ الرمز المميز لإعادة التحميل (إن أمكن)

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

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

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

الإجراءات المطلوبة لإكمال هذه الخطوة

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

  • إعادة توجيه معرّف الموارد المنتظم (URI)
    • تحدِّد الصفحة التي تتم إعادة توجيه المستخدم إليها بعد صفحة بنود الخدمة في "إحصاءات Google". ويمكن أن يختلف عن معرّف الموارد المنتظم (URI) الخاص بإعادة التوجيه المحدّد خلال مسار تفويض OAuth 2.0.
    • يجب أن تتطابق قيمة معلّمة معرّف الموارد المنتظم (URI) الخاصة بإعادة التوجيه تمامًا مع إحدى القيم المسجّلة في وحدة تحكّم مطوّري برامج Google (بما في ذلك مخططات http أو https وحالة الأحرف اللاحقة و##39;/').
  • حقول الحساب
    • السمة 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" (ملاحظة: هذا المستند غير مضمّن في هذا المستند. اطّلع على واجهة برمجة تطبيقات الإدارة للحصول على تفاصيل حول كيفية الوصول إلى بيانات إعداد المستخدم على "إحصاءات Google".

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

طلب تفاصيل الحساب بعد التفويض

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

  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" .
  7. يقبل المستخدم بنود الخدمة.
  8. تتم إعادة توجيه المستخدم إلى مقدّم الخدمة وتظهر له رسالة نجاح تفيد بأنه قد تم إنشاء حساب "إحصاءات Google" بنجاح مع تفاصيل عن الحساب وكيفية الوصول إليه.

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

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

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