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

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

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

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 Analytics API، اطّلِع على أدلة المطوِّرين لمراجع الإعداد وإعداد التقارير.
overwriteDefaultScopes	النوع:  boolean يشير إلى ما إذا كان الخيار scopes سيحلّ محلّ نطاقات واجهة برمجة التطبيقات المضمّنة التلقائية أو سيضيف إليها. سيؤدي تحديد 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();

DataChart

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();

ViewSelector

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 يتم تنشيطها في أي وقت يختار فيه المستخدم طريقة عرض جديدة من القوائم المنسدلة. ويتم تنشيطها أيضًا عند عرض مثيل "أداة اختيار العرض" لأول مرة ويتم فيه عرض طريقة العرض التلقائية.

مثال

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