ویژگی‌های استاندارد Universal Analytics (UA) پردازش داده‌ها را در 1 ژوئیه 2023 متوقف کردند . دارایی‌های UA 360 پردازش داده‌ها را در تاریخ 1 ژوئیه 2024 متوقف خواهند کرد و برخی از ویژگی‌های UA 360 قبل از آن منسوخ خواهند شد ، زیرا ما به Google Analytics 4 منتقل می‌شویم . از Data API برای دسترسی به ویژگی های گزارش برای ویژگی های GA4 استفاده کنید.

این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

شروع شدن

بررسی اجمالی

این سند شما را از طریق یک مثال کامل از نحوه استفاده از Embed API راهنمایی می کند. پس از تکمیل، برنامه ای به شکل زیر خواهید داشت.

تصویری از مثالی که در این راهنما پوشش داده شده است.

ایجاد یک داشبورد ساده

می توانید با دنبال کردن این 2 مرحله ساده، نمونه برنامه کاربردی را روی سرور خود اجرا کنید:

یک شناسه مشتری جدید ایجاد کنید
کد را کپی و پیست کنید

بعد از اینکه این برنامه را راه اندازی کردید، بخش بعدی به طور مفصل توضیح می دهد که چگونه همه قطعات با هم قرار می گیرند.

یک شناسه مشتری جدید ایجاد کنید

Embed API تقریباً با ارائه یک مؤلفه ورود به سیستم با یک کلیک که از جریان آشنای OAuth 2.0 استفاده می کند، تقریباً تمام فرآیند مجوز را برای شما انجام می دهد. برای اینکه این دکمه روی صفحه شما کار کند، به شناسه مشتری نیاز دارید.

اگر هرگز شناسه مشتری ایجاد نکرده اید، می توانید با دنبال کردن این دستورالعمل ها این کار را انجام دهید.

همانطور که دستورالعمل ها را دنبال می کنید، مهم است که این دو مرحله مهم را نادیده نگیرید:

Analytics API را فعال کنید
مبدأ صحیح را تنظیم کنید

مبدا کنترل می کند که چه دامنه هایی مجاز به استفاده از این کد برای مجوز دادن به کاربران هستند. این باعث می‌شود افراد دیگر نتوانند کد شما را کپی کرده و آن را در سایت خود اجرا کنند.

به عنوان مثال، اگر وب سایت شما در دامنه 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: کانتینرهای کامپوننت را ایجاد کنید

اکثر اجزای Embed API چیزی را به صورت بصری در صفحه شما ارائه می کنند. روشی که شما کنترل می کنید آن اجزا کجا بروند، با ایجاد کانتینرهایی برای آنهاست. در برنامه مثال ما یک دکمه auth، یک نمایش انتخابگر و یک نمودار داریم. هر یک از این مؤلفه ها در داخل عناصر HTML زیر رندر می شوند:

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

همانطور که در مثال های بعدی خواهید دید، هنگام ایجاد یک کامپوننت، به آن می گویید که از چه کانتینری با ویژگی ID آن استفاده کند.

مرحله 2: کتابخانه را بارگیری کنید

Embed 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: به کاربر مجوز دهید

Embed API با ارائه یک جزء ورود به سیستم با یک کلیک که از جریان آشنای OAuth 2.0 استفاده می کند، تقریباً تمام فرآیند مجوز را برای شما انجام می دهد. برای اینکه این دکمه روی صفحه شما کار کند، باید یک مرجع کانتینر و شناسه مشتری خود را ارسال کنید.

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

این یک دکمه در داخل عنصر با شناسه "دکمه تایید" ایجاد می کند که از جریان مجوز برای شما مراقبت می کند.

مرحله 4: انتخابگر view را ایجاد کنید

مولفه انتخابگر View را می توان برای به دست آوردن شناسه های یک نمای خاص استفاده کرد، بنابراین می توانید یک گزارش برای آن اجرا کنید.

برای ایجاد یک نمایش انتخابگر، تنها چیزی که نیاز دارید مرجع کانتینری است که در مرحله 1 ایجاد کردید.

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

این مولفه انتخابگر view را ایجاد می کند، اما هنوز آن را در صفحه نمایش نمی دهد. برای این کار باید execute() را فراخوانی کنید که در مرحله 6 مدیریت می شود.

مرحله 5: نمودار جدول زمانی را ایجاد کنید

Embed API یک جزء نمودار را در اختیار شما قرار می دهد که هم یک نمودار گوگل و هم یک شی گزارش در یکی است. این روند نمایش داده ها را بسیار ساده می کند زیرا شی نمودار گزارش های شما را در پشت صحنه اجرا می کند و به طور خودکار با نتایج به روز می شود.

برای ایجاد یک جزء نمودار، باید پارامترهای پرس و جو API و همچنین گزینه های نمودار را مشخص کنید. در گزینه های نمودار یک مرجع به شناسه کانتینری که در مرحله 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'
  }
});

مانند انتخابگر view، این مولفه نمودار را ایجاد می کند، اما برای ارائه آن به صفحه باید execute() را فراخوانی کنید، که در مرحله بعد توضیح داده خواهد شد.

مرحله 6: اجزا را به هم متصل کنید تا با هم کار کنند

مؤلفه‌های Embed API زمانی که اتفاقات مختلفی مانند مجوز موفقیت‌آمیز، انتخاب نمای جدید یا ارائه کامل نمودار رخ می‌دهد، رویدادها را منتشر می‌کنند.

برنامه مثال در این راهنما منتظر می‌ماند تا انتخابگر view تا زمانی که مجوز انجام شود رندر شود، و هر زمان که نمای جدیدی از انتخابگر view انتخاب شد، نمودار خط زمانی را به‌روزرسانی می‌کند.

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

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

برای فهرست کاملی از همه رویدادهایی که اجزای مختلف منتشر می‌کنند، مرجع API را بررسی کنید.

مراحل بعدی

این راهنما شما را با نحوه ایجاد یک تجسم اولیه با Embed API آشنا کرد. اگر می‌خواهید بیشتر بدانید، مرجع API را بررسی کنید تا درک کاملی از آنچه ممکن است داشته باشید.