البدء

نظرة عامة

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

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

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

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

  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: إنشاء حاويات المكوّنات

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

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

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

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

يمكن تحميل واجهة برمجة تطبيقات التضمين باستخدام المقتطف التالي.

<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' ID الذي يعتني بتدفق التفويض نيابةً عنك.

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

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

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

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

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

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

توفّر لك واجهة برمجة التطبيقات Include 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();
});

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

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

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