Tổng quan
Tài liệu này sẽ hướng dẫn bạn một ví dụ đầy đủ về cách sử dụng API Nhúng. Sau khi hoàn tất, bạn sẽ có một ứng dụng có dạng như sau.
Tạo một trang tổng quan đơn giản
Bạn có thể chạy ứng dụng mẫu trên máy chủ của mình bằng cách làm theo 2 bước đơn giản sau:
- Tạo một mã ứng dụng khách mới
- Sao chép và dán mã
Sau khi bạn thiết lập và chạy ứng dụng này, phần tiếp theo sẽ giải thích chi tiết về cách thức tất cả các thành phần khớp với nhau.
Tạo một mã ứng dụng khách mới
API Nhúng xử lý hầu hết mọi quy trình uỷ quyền cho bạn bằng cách cung cấp thành phần đăng nhập bằng một lần nhấp, sử dụng quy trình OAuth 2.0 quen thuộc. Để nút này hoạt động trên trang của bạn, bạn cần có một ID ứng dụng khách.
Nếu chưa từng tạo mã ứng dụng khách, bạn có thể tạo bằng cách làm theo các hướng dẫn này.
Khi thực hiện hướng dẫn, bạn không được bỏ qua hai bước quan trọng này:
- Bật Analytics API
- Thiết lập đúng nguồn gốc
Nguồn gốc kiểm soát những miền được phép sử dụng mã này để uỷ quyền cho người dùng. Việc này sẽ ngăn người khác sao chép mã của bạn và chạy mã đó trên trang web của họ.
Ví dụ: nếu trang web của bạn được lưu trữ trên miền example.com, hãy nhớ đặt nguồn gốc sau đây cho mã ứng dụng khách http://example.com. Nếu muốn kiểm thử mã cục bộ, bạn cũng cần thêm nguồn gốc cho máy chủ cục bộ, ví dụ: http://localhost:8080.
Sao chép và dán mã
Sau khi có ID ứng dụng khách với nhóm gốc phù hợp, bạn đã sẵn sàng tạo bản minh hoạ. Chỉ cần sao chép và dán mã sau vào tệp HTML trên trình cắm máy chủ của bạn, trong ID ứng dụng khách của bạn, nơi có nội dung: "Chèn ID ứng dụng khách của bạn tại đây".
<!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>
Hướng dẫn từng bước về mã
Phần này sẽ hướng dẫn bạn từng bước một cách chính xác những gì đang diễn ra trong mã được cung cấp cho ứng dụng mẫu. Sau khi hiểu được cách hoạt động của API này, bạn sẽ có thể tạo bản ghi của riêng mình.
Bước 1: Tạo vùng chứa thành phần
Hầu hết các thành phần API Nhúng sẽ hiển thị nội dung trực quan trên trang của bạn. Bạn có thể kiểm soát vị trí của các thành phần đó bằng cách tạo vùng chứa cho chúng. Trong ứng dụng mẫu, chúng ta có nút xác thực, bộ chọn khung hiển thị và biểu đồ. Mỗi thành phần này được hiển thị bên trong các phần tử HTML sau:
<section id="auth-button"></section> <section id="view-selector"></section> <section id="timeline"></section>
Khi tạo một thành phần, bạn cho thành phần đó biết cần sử dụng vùng chứa nào theo thuộc tính mã nhận dạng, như bạn sẽ thấy trong các ví dụ sau.
Bước 2: Tải thư viện
Bạn có thể tải API Nhúng bằng đoạn mã sau.
<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>
Khi thư viện được tải đầy đủ, mọi lệnh gọi lại được truyền đến gapi.analytics.ready sẽ được gọi.
<script>
gapi.analytics.ready(function() {
// Put your application code here...
});
</script>
Bước 3: Uỷ quyền người dùng
API Nhúng xử lý hầu hết quy trình uỷ quyền cho bạn bằng cách cung cấp thành phần đăng nhập bằng một lần nhấp, sử dụng quy trình OAuth 2.0 quen thuộc. Để nút này hoạt động trên trang của bạn, bạn cần chuyển tệp tham chiếu vùng chứa và mã ứng dụng khách vào.
gapi.analytics.auth.authorize({
container: 'auth-button',
clientid: CLIENT_ID,
});
Thao tác này sẽ tạo một nút bên trong phần tử có mã nhận dạng "nút xác thực" giúp xử lý quy trình uỷ quyền cho bạn.
Bước 4: Tạo bộ chọn chế độ xem
Bạn có thể sử dụng thành phần Bộ chọn chế độ xem để lấy mã nhận dạng của một chế độ xem cụ thể, nhờ đó, bạn có thể chạy báo cáo cho chế độ xem đó.
Để tạo một bộ chọn chế độ xem, bạn chỉ cần tham chiếu vùng chứa mà bạn đã tạo ở bước 1.
var viewSelector = new gapi.analytics.ViewSelector({
container: 'view-selector'
});
Thao tác này sẽ tạo thành phần bộ chọn khung hiển thị, nhưng chưa hiển thị thành phần đó trên trang. Để làm việc đó, bạn cần gọi execute(). Cách này được xử lý trong bước 6.
Bước 5: Tạo biểu đồ dòng thời gian
API Nhúng cung cấp cho bạn thành phần biểu đồ vừa là biểu đồ của Google vừa là đối tượng báo cáo trong một. Việc này giúp đơn giản hoá đáng kể quy trình hiển thị dữ liệu vì đối tượng biểu đồ sẽ chạy báo cáo phía sau cảnh và tự động cập nhật kết quả.
Để tạo một thành phần biểu đồ, bạn cần chỉ định các tham số truy vấn API cũng như các tuỳ chọn biểu đồ. Trong các tuỳ chọn biểu đồ là mã tham chiếu đến mã của vùng chứa mà bạn đã tạo ở bước 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'
}
});
Giống như bộ chọn chế độ xem, thao tác này sẽ tạo thành phần biểu đồ nhưng để hiển thị thành phần đó cho trang, bạn cần gọi execute(). Điều này sẽ được giải thích trong bước tiếp theo.
Bước 6: Kết nối các thành phần để hoạt động cùng nhau
Các thành phần API được nhúng sẽ phát ra các sự kiện khi nhiều sự kiện xảy ra, chẳng hạn như uỷ quyền thành công, chọn một chế độ xem mới hoặc một biểu đồ đang được hiển thị đầy đủ.
Ứng dụng mẫu trong hướng dẫn này sẽ chờ kết xuất bộ chọn chế độ xem cho đến khi uỷ quyền xong và sẽ cập nhật biểu đồ dòng thời gian mỗi khi có một chế độ xem mới được chọn từ bộ chọn chế độ xem.
gapi.analytics.auth.on('success', function(response) {
viewSelector.execute();
});
viewSelector.on('change', function(ids) {
var newIds = {
query: {
ids: ids
}
}
timeline.set(newIds).execute();
});
Để biết danh sách đầy đủ tất cả các sự kiện mà các thành phần khác nhau phát ra, hãy xem Tài liệu tham khảo API.
Các bước tiếp theo
Hướng dẫn này đã hướng dẫn bạn cách tạo hình ảnh cơ bản bằng API Nhúng. Nếu bạn muốn tìm hiểu thêm, hãy xem tài liệu tham khảo API để hiểu đầy đủ về những gì có thể.