دليل البدء

نظرة عامة

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

لقطة شاشة للمثال الوارد في هذا الدليل
لقطة شاشة للمثال الذي يتناوله هذا الدليل.

إنشاء لوحة معلومات بسيطة

يمكنك تشغيل نموذج التطبيق على خادمك باتباع هاتين الخطوتين السهلتين:

  1. إنشاء معرّف عميل جديد
  2. انسخ الرمز والصقه.

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

إنشاء معرّف عميل جديد

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

إذا لم يسبق لك إنشاء معرّف عميل، يمكنك إجراء ذلك باتّباع هذه التعليمات.

أثناء مراجعة التعليمات، من المهم ألا تغفل هاتين الخطوتين المهمتين:

  • تفعيل واجهة برمجة تطبيقات "إحصاءات Google"
  • قم بتعيين المصادر الصحيحة

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

على سبيل المثال، إذا كان موقعك الإلكتروني مستضافًا على النطاق example.com، تأكّد من ضبط المصدر التالي لمعرّف العميل http://example.com. إذا أردت اختبار الرمز محليًا، ستحتاج إلى إضافة المصدر للخادم المحلي أيضًا، على سبيل المثال: http://localhost:8080.

نسخ الرمز ولصقه

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

<!DOCTYPE html>
<html>
<head>
  <title>Embed API Demo</title>
</head>
<body>

<!-- Step 1: Create the containing elements. -->

<section id="auth-button"></section>
<section id="view-selector"></section>
<section id="timeline"></section>

<!-- Step 2: Load the library. -->

<script>
(function(w,d,s,g,js,fjs){
  g=w.gapi||(w.gapi={});g.analytics={q:[],ready:function(cb){this.q.push(cb)}};
  js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
  js.src='https://apis.google.com/js/platform.js';
  fjs.parentNode.insertBefore(js,fjs);js.onload=function(){g.load('analytics')};
}(window,document,'script'));
</script>
<script>
gapi.analytics.ready(function() {

  // Step 3: Authorize the user.

  var CLIENT_ID = 'Insert your client ID here';

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

  // Step 4: Create the view selector.

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

  // Step 5: Create the timeline chart.

  var timeline = new gapi.analytics.googleCharts.DataChart({
    reportType: 'ga',
    query: {
      'dimensions': 'ga:date',
      'metrics': 'ga:sessions',
      'start-date': '30daysAgo',
      'end-date': 'yesterday',
    },
    chart: {
      type: 'LINE',
      container: 'timeline'
    }
  });

  // Step 6: Hook up the components to work together.

  gapi.analytics.auth.on('success', function(response) {
    viewSelector.execute();
  });

  viewSelector.on('change', function(ids) {
    var newIds = {
      query: {
        ids: ids
      }
    }
    timeline.set(newIds).execute();
  });
});
</script>
</body>
</html>

جولة تفصيلية حول الرمز

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

الخطوة 1: إنشاء حاويات المكوّنات

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

<section id="auth-button"></section>
<section id="view-selector"></section>
<section id="timeline"></section>

عند إنشاء مكوّن، عليك إخباره بالحاوية التي يجب استخدامها من خلال سمة المعرّف، كما ستلاحظ في الأمثلة اللاحقة.

الخطوة 2: تحميل المكتبة

يمكن تحميل inline API بالمقتطف التالي.

<script>
(function(w,d,s,g,js,fjs){
  g=w.gapi||(w.gapi={});g.analytics={q:[],ready:function(cb){this.q.push(cb)}};
  js=d.createElement(s);fjs=d.getElementsByTagName(s)[0];
  js.src='https://apis.google.com/js/platform.js';
  fjs.parentNode.insertBefore(js,fjs);js.onload=function(){g.load('analytics')};
}(window,document,'script'));
</script>

عند تحميل المكتبة بالكامل، سيتم استدعاء أي عمليات استدعاء يتم تمريرها إلى gapi.analytics.ready.

<script>
gapi.analytics.ready(function() {
  // Put your application code here...
});
</script>

الخطوة 3: تفويض المستخدم

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

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

سيؤدي هذا إلى إنشاء زر داخل العنصر باستخدام معرف "auth-button" الذي يعتني بتدفق التفويض نيابة عنك.

الخطوة 4: إنشاء أداة اختيار الملفات الشخصية

يمكن استخدام مكوِّن أداة اختيار الملفات الشخصية للحصول على أرقام تعريف ملف شخصي معين، حتى تتمكن من تشغيل تقرير له.

لإنشاء أداة اختيار الملفات الشخصية، كل ما تحتاجه هو مرجع الحاوية الذي أنشأته في الخطوة 1.

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

يؤدي هذا إلى إنشاء مكوِّن أداة اختيار طرق العرض، لكنه لا يعرضه على الصفحة بعد. لإجراء ذلك، عليك الاتصال بـ execute()، ويتم التعامل مع هذه المشكلة في الخطوة 6.

الخطوة 5: إنشاء مخطط المخطط الزمني

تزوِّدك واجهة برمجة التطبيقات inline API بمكوِّن رسم بياني يمثّل مخطط Google وكائن تقرير في الوقت نفسه. يعمل هذا على تبسيط عملية عرض البيانات إلى حد كبير، حيث يشغّل كائن المخطط التقارير وراء المشهد ويحدِّث نفسه تلقائيًا بالنتائج.

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

var timeline = new gapi.analytics.googleCharts.DataChart({
  reportType: 'ga',
  query: {
    'dimensions': 'ga:date',
    'metrics': 'ga:sessions',
    'start-date': '30daysAgo',
    'end-date': 'yesterday',
  },
  chart: {
    type: 'LINE',
    container: 'timeline'
  }
});

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

الخطوة 6: ربط المكوّنات للعمل معًا

تنبعث مكوِّنات واجهة برمجة التطبيقات المضمّنة أحداثًا عند حدوث أمور متعددة مثل اجتياز التفويض أو اختيار طريقة عرض جديدة أو عرض رسم بياني بالكامل.

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

gapi.analytics.auth.on('success', function(response) {
  viewSelector.execute();
});

viewSelector.on('change', function(ids) {
  var newIds = {
    query: {
      ids: ids
    }
  }
  timeline.set(newIds).execute();
});

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

الخطوات التالية

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