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

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

مقدمة

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

قبل البدء

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

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

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

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

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

نظرة عامة

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

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

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

التدفق الفني

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

  1. اطلب من المستخدم المصادقة والتفويض للتطبيق/الخدمة باستخدام OAuth 2.0.
  2. أنشئ تذكرة حساب باستخدام واجهة برمجة التطبيقات لإدارة الحسابات.
  3. أعِد توجيه المستخدم إلى قبول بنود الخدمة (TOS) في "إحصاءات 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.

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

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

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

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

باستخدام رمز الدخول للمستخدم الذي تم الحصول عليه أثناء المصادقة والتفويض، يتم إرسال طلب 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. (اختياري) فرص الدمج

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

  • أدخِل مقتطف تتبُّع "إحصاءات Google" العادي تلقائيًا باستخدام رقم تعريف الموقع للحساب الذي تم إنشاؤه حديثًا، وذلك لكل صفحة على الموقع الإلكتروني للمستخدم، إن أمكن.
  • ضبط موقع المستخدم تلقائيًا باستخدام Management API.
  • قدِّم تقارير عن مستخدم داخل منتجك (على سبيل المثال، في لوحة المشرف) باستخدام embed API أو Core Reporting API.

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

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

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

  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 لموقع الويب، واسم الموقع الإلكتروني، والمنطقة الزمنية، وما إلى ذلك)، فيمكن عندئذٍ تبسيط كلا الخيارين أعلاه عن طريق:

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