مرجع المكونات المضمّن

ويوضّح هذا المستند الخيارات والأساليب والخصائص والأحداث لجميع مكوّنات واجهة برمجة التطبيقات Include API المضمّنة.

أخفقت المصادقة

gapi.analytics.auth

مكوّن المصادقة هو عبارة عن نغمة فردية يمكن استخدامها لتفويض المستخدم.

الطُرق
authorize(options:Object)	طلبات الإرجاع: gapi.analytics.auth يعرض زر تسجيل الدخول إلى "إحصاءات Google" داخل الحاوية المحددة والتي تسمح للمستخدم بتسجيل الدخول باستخدام حسابه على Google.
isAuthorized()	طلبات الإرجاع: boolean عرض true إذا وافق المستخدم بنجاح، أو false بدلاً من ذلك.
signOut()	طلبات الإرجاع: gapi.analytics.auth يسجِّل خروج المستخدم الحالي. يؤدي ذلك أيضًا إلى تشغيل الحدث signOut.
getAuthResponse()	طلبات الإرجاع: Object للحصول على بيانات المصادقة التي يعرضها طلب التفويض الأصلي. يتضمن العنصر المعروض رمز الدخول الذي يمكن عادةً تقديمه يدويًا للطلبات التي تمت مصادقتها.
getUserProfile()	طلبات الإرجاع: Object يحصل على معلومات الملف الشخصي الأساسية عن المستخدم الذي سجَّل الدخول حاليًا. ويتضمن ذلك اسم المستخدم وعنوان البريد الإلكتروني وصورة الملف الشخصي العلنية (في حال ضبطها).

الطرق المكتسَبة
on
once
off

الخيارات
clientId	النوع: string معرِّف العميل لمشروعك في وحدة تحكم مطوري البرامج.
container	النوع: string|HTMLElement رقم تعريف عنصر HTML في DOM الذي سيستضيف زر تسجيل الدخول ويمكنك أيضًا تمرير مرجع إلى العنصر نفسه.
userInfoLabel	النوع: string النص الذي سيتم عرضه قبل عنوان البريد الإلكتروني لمستخدم تم تسجيل دخوله. القيمة التلقائية هي 'You are logged in as: '.
scopes	النوع: Array قائمة بنطاقات مصادقة Google API التي يطلبها تطبيقك. للاطِّلاع على جميع النطاقات المتاحة، يُرجى الانتقال إلى مساحة لعب OAuth 2.0. بالنسبة إلى نطاقات مصادقة واجهة برمجة التطبيقات في "إحصاءات Google"، اطّلع على أدلة المطوّرين لمراجع الإعداد وإعداد التقارير.
overwriteDefaultScopes	النوع: boolean تشير هذه العلامة إلى ما إذا كان الخيار scopes يستبدل نطاقات Include API التلقائية أو يضيفها. سيؤدي تحديد false (الخيار التلقائي) إلى إضافة النطاقات التلقائية، وسيؤدي تحديد true إلى استبدالها بالنطاقات المحدّدة في خيار scopes. قيمة النطاقات التلقائية هي: ['https://www.googleapis.com/auth/analytics.readonly']. ملاحظة: إنّ المصادقة عبر واجهة برمجة تطبيقات التضمين تتطلب الوصول إلى الملف الشخصي الأساسي للمستخدم. ولا يمكن استبدال هذه النطاقات.
serverAuth.access_token	النوع: string إذا كان لديك رمز دخول صالح، يمكنك تمريره إلى طريقة التفويض مباشرةً ولن يُطلب من المستخدم التفويض. للتعرُّف على تفاصيل عن كيفية استرداد رمز الدخول، يُرجى الاطِّلاع على وثائق OAuth 2.0.

الأحداث
signIn	الوسيطات: لا شيء يتم الإطلاق عند تسجيل المستخدم الدخول بنجاح.
signOut	الوسيطات: لا شيء يتم الإطلاق عندما يسجِّل المستخدم الخروج بنجاح.
needsAuthorization	الوسيطات: لا شيء عند استدعاء الطريقة gapi.analytics.auth.authorize، يتم إجراء عملية تحقق مبدئية لمعرفة ما إذا كان المستخدم قد سجّل الدخول حاليًا. وفي حال لم يسجِّل المستخدم الدخول، يتم تنشيط هذا الحدث للإشارة إلى ما إذا كان هناك حاجة إلى مزيد من التفويض.
error	الوسيطات: response يتم الإطلاق عند حدوث خطأ أثناء عملية المصادقة. إذا كنت تريد تلقّي رسالة الخطأ من كائن الرد، سيكون عند الساعة response.error.message.

الأحداث التي تم إيقافها نهائيًا
success	الوسيطات: response هذا الحدث متوافق مع الأنظمة القديمة وقد تتم إزالته في إصدار مستقبلي. استخدِم الحدث signIn بدلاً من ذلك.

مثال

// Standard client-side authorization.

gapi.analytics.auth.authorize({
  clientId: 'XXXXXX',
  container: 'auth-button'
});

gapi.analytics.auth.on('signIn', function() {
  console.log(gapi.analytics.auth.getUserProfile());
});

// Authorization using an access token obtained server-side.
// You do not need to register an event handler because
// authorization happens immediately.

gapi.analytics.auth.authorize({
  serverAuth: {
    access_token: 'XXXXXX'
  }
});

ملاحظة: يحدث التفويض على الفور عند استخدام serverAuth.access_token، لذلك لا داعي لتسجيل معالج حدث.

ملاحظة مهمة: عند استخدام serverAuth.access_token، عليك الاختيار من أجل التأكّد من أنّ الرمز المميّز صالح وليس منتهي الصلاحية. لمعرفة التفاصيل حول كيفية إعادة تحميل رمز الدخول الذي انتهت صلاحيته، يمكنك الاطّلاع على مستندات OAuth 2.0.

البيانات

gapi.analytics.report.Data

الشركة المصنِّعة
Data(options:Object)	يتيح لك مكوّن البيانات إجراء طلبات بحث في واجهة برمجة التطبيقات لإعداد التقارير الأساسية في "إحصاءات Google" والحصول على النتائج مرة أخرى.

الخيارات
query	النوع: Object عنصر يحتوي على معلمات طلب البحث من Core Reporting API. يتم استخدام القيم التلقائية التالية بالإضافة إلى الإعدادات التلقائية العادية التي توفّرها واجهة برمجة التطبيقات: { 'start-date': '7daysAgo', 'end-date': 'yesterday }

الطرق المكتسَبة
get
set
execute
on
once
off
emit

الأحداث
success	الوسيطات: response يتم الإطلاق عند اكتمال طلب البحث بنجاح.
error	الوسيطات: response يتم الإطلاق عند حدوث خطأ أثناء عملية طلب البحث. إذا كنت تريد تلقّي رسالة الخطأ من كائن الرد، سيكون عند الساعة response.error.message.

مثال

var report = new gapi.analytics.report.Data({
  query: {
    ids: 'ga:XXXX',
    metrics: 'ga:sessions',
    dimensions: 'ga:city'
  }
});

report.on('success', function(response) {
  console.log(response);
});

report.execute();

رسم بياني للبيانات

gapi.analytics.googleCharts.DataChart

الشركة المصنِّعة
DataChart(options:Object)	يعمل DataChart على التفاف الرسم البياني العادي من Google ومكوّن البيانات حتى تتمكن بسهولة من إنشاء عرض مرئي لطلب البحث بدون الحاجة إلى ربطه بنفسك.

الخيارات
query	النوع: Object اطّلع على خيار طلب البحث لمكوّن البيانات.
chart	النوع: Object يمكنك الاطّلاع على التفاصيل أدناه لمعرفة خيارات الرسم البياني الفردية.
chart.container	النوع: string|HTMLElement رقم تعريف أحد عناصر HTML في DOM الذي سيستضيف "الرسم البياني للبيانات". ويمكنك أيضًا تمرير مرجع إلى العنصر نفسه.
chart.type	النوع: string نوع الرسم البياني الخيارات المتاحة هي: LINE وCOLUMN وBAR وTABLE وGEO.
chart.options	النوع: Object أي خيارات يمكن تمريرها إلى كائن الرسم البياني من Google المقابل.

الطرق المكتسَبة
get
set
execute
on
once
off
emit

الأحداث
success	الوسيطات: result يتم الإطلاق عند اكتمال طلب البحث بنجاح وعندما يتم عرض الرسم البياني بالكامل. result.chart – مثيل "رسم بياني من Google". result.data – استجابة التقرير بتنسيق مَعلمة البيانات. result.dataTable – مثيل DataTable الذي تم إنشاؤه من الكائن result.data. result.response – كائن الاستجابة لواجهة برمجة التطبيقات الأولية.
error	الوسيطات: response يتم الإطلاق عند حدوث خطأ أثناء عملية الطلب أو العرض. إذا كنت تريد تلقّي رسالة الخطأ من كائن الرد، سيكون عند الساعة response.error.message.

مثال

var chart = new gapi.analytics.googleCharts.DataChart({
  query: {
    ids: 'ga:XXXX',
    metrics: 'ga:sessions',
    dimensions: 'ga:date'
  },
  chart: {
    type: 'LINE',
    container: 'line-chart',
    options: {
      title: 'Sessions over the past week.',
      fontSize: 12
    }
  }
});
chart.on('success', function(response) {
  // response.chart : the Google Chart instance.
  // response.data : the Google Chart data object.
});

chart.execute();

أداة اختيار الملف الشخصي

gapi.analytics.ViewSelector

الشركة المصنِّعة
ViewSelector(options:Object)	يسمح لك المكوّن ViewSelector باختيار حسابك وموقعك وملفك الشخصي من خلال القوائم المنسدلة.

الخيارات
container	النوع: string|HTMLElement رقم تعريف عنصر HTML في DOM الذي سيستضيف في ViewSelector. ويمكنك أيضًا تمرير مرجع إلى العنصر نفسه.

الطرق المكتسَبة
get
set
execute
on
once
off
emit

مواقع المثال
ids	النوع: string رقم تعريف الجدول الفريد للنموذج ga:XXXX، حيث يكون XXXX هو رقم تعريف الملف الشخصي في "إحصاءات Google".

الأحداث
change	الوسيطات: ids يتم الإطلاق في أي وقت يختار فيه المستخدم ملفًا شخصيًا جديدًا من القوائم المنسدلة. ويتم تنشيطه أيضًا عند عرض مثيل ViewSelector لأول مرة وعرض العرض التلقائي.

مثال

var viewSelector = new gapi.analytics.ViewSelector({
  container: 'view-selector'
});

viewSelector.on('change', function(ids) {
  console.log(ids);
});

viewSelector.execute();

طرق المكوّنات المشتركة

الطُرق
set(options)	طلبات الإرجاع: this يحدّد خيارات ضبط المكوّنات أو يعدّلها (يمكن إجراء ذلك أيضًا في وقت الإنشاء في المُنشئ).
get()	طلبات الإرجاع: Object لعرض خيارات الإعداد الحالية لأحد المكونات.
execute()	طلبات الإرجاع: this يستدعي الإجراء الأساسي للمكوّن. يكون هذا عادةً عرض محتوى على الصفحة أو تشغيل تقرير (أو كليهما).
on(event, handler)	طلبات الإرجاع: this تسجِّل دالة لاستدعاءها عندما يصدر المكوِّن الحدث المحدَّد.
once(event, handler)	طلبات الإرجاع: this تسجِّل دالة سيتم استدعاؤها عند وقوع الحدث التالي فقط. بعد تشغيل المعالج بعد إلغاء تسجيله تلقائيًا.
off(opt_event, opt_handler)	طلبات الإرجاع: undefined إزالة معالج حدث من أحد المكونات. إذا لم يتم تمرير أي معالج، ستتم إزالة جميع معالجات الحدث الذي تم اجتيازه. في حال عدم تمرير أي حدث، سيؤدي ذلك إلى إزالة جميع معالجات جميع الأحداث.
emit(event, ...opt_args)	طلبات الإرجاع: undefined يتم إنشاء حدث. ويمكنك اختيار الوسيطات المُراد تمريرها إلى أي معالجات مسجّلة.

set

يحدّد خيارات ضبط المكوّنات أو يعدّلها (يمكن إجراء ذلك أيضًا في وقت الإنشاء في المُنشئ).

الاستخدام

component.set(options);

المَعلمات

الاسم	النوع	الوصف
options	Object	خيارات الإعداد لهذا المكوِّن. سيتم دمج الخيارات التي تم اجتيازها مع الخيارات الحالية.

المرتجعات

this – مثيل المكوّن

---

get

لعرض خيارات الإعداد الحالية لأحد المكونات.

المرتجعات

Object – خيارات الضبط الحالية للمكوّن.

---

execute()

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

المرتجعات

this – مثيل المكوّن

---

on(event, handler)

تسجِّل دالة لاستدعاءها عندما يصدر المكوِّن الحدث المحدَّد.

المَعلمات

الاسم	النوع	الوصف
event	string	اسم الحدث.
handler	Function	الدالة التي سيتم استدعاؤها عند وقوع الحدث. (راجِع مراجع الأحداث الفردية للحصول على تفاصيل المعلَمة).

المرتجعات

this – مثيل المكوّن

---

once(event, handler)

تسجِّل دالة سيتم استدعاؤها عند وقوع الحدث التالي فقط. بعد تشغيل المعالج بعد إلغاء تسجيله تلقائيًا.

المَعلمات

الاسم	النوع	الوصف
event	string	اسم الحدث.
handler	Function	الدالة التي سيتم استدعاؤها عند وقوع الحدث. (راجِع مراجع الأحداث الفردية للحصول على تفاصيل المعلَمة).

المرتجعات

this – مثيل المكوّن

---

off(opt_event, opt_handler)

إزالة معالج حدث من أحد المكونات. إذا لم يتم تمرير أي معالج، ستتم إزالة جميع معالجات الحدث الذي تم اجتيازه. في حال عدم تمرير أي حدث، سيؤدي ذلك إلى إزالة جميع معالجات جميع الأحداث.

المَعلمات

الاسم	النوع	الوصف
opt_event	string	اسم الحدث. إذا لم يتم تحديد أي حدث، تتم إزالة جميع معالجات جميع الأحداث. اختياري:
opt_handler	Function	مرجع إلى معالج الدالة المطلوب إزالته. في حال عدم تمرير أي دالة، تتم إزالة جميع المعالجات. اختياري:

المرتجعات

undefined

---

emit(event, ...opt_args)

يتم إنشاء حدث. ويمكنك اختيار الوسيطات المُراد تمريرها إلى أي معالجات مسجّلة.

المَعلمات

الاسم	النوع	الوصف
event	string	اسم الحدث.
...opt_args	*	سيتم تمرير الوسيطات الاختيارية إلى أي معالجات أحداث مسجّلة.

المرتجعات

undefined