Przegląd
Ten dokument zawiera pełny przykład użycia interfejsu Embed API. Po zakończeniu otrzymasz zgłoszenie podobne do tego.
Tworzenie prostego panelu informacyjnego
Aby uruchomić przykładową aplikację na swoim serwerze, wykonaj te 2 proste kroki:
- Utwórz nowy identyfikator klienta
- Skopiuj i wklej kod
Gdy aplikacja będzie już gotowa, w następnej sekcji znajdziesz szczegółowe wyjaśnienie, jak wszystkie elementy są ze sobą powiązane.
Tworzenie nowego identyfikatora klienta
Interfejs Embed API obsługuje prawie cały proces autoryzacji, udostępniając komponent logowania jednym kliknięciem, który korzysta ze znanego procesu OAuth 2.0. Aby przycisk działał na Twojej stronie, potrzebujesz identyfikatora klienta.
Jeśli nie masz jeszcze utworzonego identyfikatora klienta, możesz go utworzyć, postępując zgodnie z tymi instrukcjami.
Podczas wykonywania instrukcji pamiętaj, aby nie pominąć tych 2 kluczowych kroków:
- Włączanie interfejsu Analytics API
- Ustaw prawidłowe źródła
Źródła określają, które domeny mogą używać tego kodu do autoryzowania użytkowników. Dzięki temu inne osoby nie będą mogły skopiować kodu i uruchomić go w swojej witrynie.
Jeśli na przykład Twoja witryna jest hostowana w domenie example.com, ustaw to źródło dla identyfikatora klienta http://example.com. Jeśli chcesz przetestować kod lokalnie, musisz też dodać punkt początkowy swojego serwera lokalnego, np. http://localhost:8080.
Skopiuj i wklej kod
Po ustaleniu identyfikatora klienta z odpowiednimi źródłami możesz utworzyć wersję demonstracyjną. Wystarczy skopiować i wkleić ten kod do pliku HTML na serwerze, umieszczając tam swój identyfikator klienta w polu „Tu wstawić swój identyfikator klienta”.
<!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>
Przewodnik po kodzie
W tej sekcji omawiamy krok po kroku, co dokładnie dzieje się w kodzie udostępnionym w przykładowej aplikacji. Gdy już zrozumiesz, jak działa ta technologia, nauczysz się tworzyć własne.
Krok 1. Utwórz kontenery komponentów
Większość komponentów interfejsu Embed API renderuje elementy wizualne na stronie. Możesz kontrolować, gdzie znajdują się te komponenty, tworząc dla nich kontenery. W przykładowej aplikacji mamy przycisk uwierzytelniania, selektor widoku i wykres. Każdy z nich jest renderowany w tych elementach HTML:
<section id="auth-button"></section> <section id="view-selector"></section> <section id="timeline"></section>
Podczas tworzenia komponentu wskazujesz kontenerowi, którego ma użyć, za pomocą atrybutu identyfikatora, tak jak w późniejszych przykładach.
Krok 2. Wczytaj bibliotekę
Interfejs Embed API można załadować za pomocą tego fragmentu kodu.
<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>
Po pełnym wczytaniu biblioteki będą wywoływane wszystkie wywołania zwrotne przekazane do gapi.analytics.ready.
<script>
gapi.analytics.ready(function() {
// Put your application code here...
});
</script>
Krok 3. Autoryzuj użytkownika
Interfejs Embed API obsługuje niemal cały proces autoryzacji, udostępniając komponent logowania jednym kliknięciem, który korzysta ze znanego procesu OAuth 2.0. Aby przycisk działał na Twojej stronie, musisz przekazać odniesienie do kontenera i swój identyfikator klienta.
gapi.analytics.auth.authorize({
container: 'auth-button',
clientid: CLIENT_ID,
});
Spowoduje to wygenerowanie w elemencie przycisku o identyfikatorze „auth-button”, który zajmuje się przepływem autoryzacji.
Krok 4. Utwórz selektor widoku
Komponent selektora widoku pozwala uzyskać identyfikatory konkretnego widoku, aby wygenerować dla niego raport.
Aby utworzyć selektor widoku, potrzebujesz jedynie odniesienia do kontenera utworzonego w kroku 1.
var viewSelector = new gapi.analytics.ViewSelector({
container: 'view-selector'
});
Spowoduje to utworzenie komponentu selektora widoku, ale nie renderuje go jeszcze na stronie. W tym celu musisz wywołać usługę execute(), która jest obsługiwana w kroku 6.
Krok 5. Utwórz wykres z osią czasu
Interfejs Embed API udostępnia komponent wykresu, który jest zarówno wykresem Google, jak i obiektem raportu. Bardzo upraszcza to proces wyświetlania danych, ponieważ obiekt wykresu generuje raporty w tle i automatycznie aktualizuje wyniki.
Aby utworzyć komponent wykresu, musisz określić parametry zapytania API oraz opcje wykresu. Opcje wykresu odnoszą się do identyfikatora kontenera utworzonego w kroku 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'
}
});
Podobnie jak w przypadku selektora widoku powoduje to utworzenie komponentu wykresu, ale aby wyrenderować go na stronie, trzeba wywołać execute(). Zostanie to wyjaśnione w następnym kroku.
Krok 6. Połącz komponenty, aby działały razem
Komponenty interfejsu Embed API generują zdarzenia, gdy zachodzą różne okoliczności, takie jak pomyślna autoryzacja, wybór nowego widoku lub pełne wyrenderowanie wykresu.
Przykładowa aplikacja w tym przewodniku czeka na wyrenderowanie selektora widoku do momentu autoryzacji. Aktualizuje wykres z osią czasu za każdym razem, gdy w selektorze widoku zostanie wybrany nowy widok.
gapi.analytics.auth.on('success', function(response) {
viewSelector.execute();
});
viewSelector.on('change', function(ids) {
var newIds = {
query: {
ids: ids
}
}
timeline.set(newIds).execute();
});
Pełną listę wszystkich zdarzeń emitowanych przez różne komponenty znajdziesz w dokumentacji interfejsu API.
Dalsze kroki
Ten przewodnik pokazał Ci, jak utworzyć podstawową wizualizację za pomocą interfejsu Embed API. Więcej informacji znajdziesz w materiałach referencyjnych interfejsu API, z których dowiesz się, jakie są możliwości tej funkcji.