Tài liệu tham khảo về thành phần tích hợp

Tài liệu này mô tả các tuỳ chọn, phương thức, thuộc tính và sự kiện cho tất cả thành phần API Nhúng tích hợp sẵn.

xác thực

gapi.analytics.auth

Thành phần xác thực là một singleton có thể dùng để uỷ quyền cho người dùng.

Phương thức
authorize(options:Object)	Trả lại:  gapi.analytics.auth Hiển thị nút đăng nhập Google Analytics bên trong vùng chứa được chỉ định để người dùng có thể đăng nhập bằng Tài khoản Google của mình.
isAuthorized()	Trả lại:  boolean Trả về true nếu người dùng đã uỷ quyền thành công, nếu không thì trả về false.
signOut()	Trả lại:  gapi.analytics.auth Đăng xuất người dùng hiện tại. Đồng thời kích hoạt sự kiện signOut.
getAuthResponse()	Trả lại:  Object Lấy dữ liệu xác thực do yêu cầu uỷ quyền ban đầu trả về. Đối tượng được trả về bao gồm mã truy cập. Mã này thường có thể dùng để thực hiện các yêu cầu đã xác thực theo cách thủ công.
getUserProfile()	Trả lại:  Object Lấy thông tin cơ bản về hồ sơ của người dùng hiện đã đăng nhập. Thông tin này bao gồm tên, địa chỉ email và ảnh hồ sơ công khai của người dùng (nếu được đặt).

Phương thức kế thừa
on
once
off

Tùy chọn
clientId	Loại:  string Mã ứng dụng khách của dự án của bạn trong developer console.
container	Loại:  string|HTMLElement Mã của một phần tử HTML trong DOM sẽ lưu trữ nút đăng nhập. Bạn cũng có thể chuyển tham chiếu đến chính phần tử đó.
userInfoLabel	Loại:  string Văn bản sẽ hiển thị trước địa chỉ email của người dùng đã đăng nhập. Giá trị mặc định là 'You are logged in as: '.
scopes	Loại:  Array Danh sách phạm vi xác thực API của Google mà ứng dụng của bạn đang yêu cầu. Để xem tất cả các phạm vi có sẵn, hãy truy cập Play OAuth 2.0 Playground. Đối với phạm vi xác thực API Google Analytics, hãy xem hướng dẫn cho nhà phát triển về các tài nguyên Cấu hình và Báo cáo.
overwriteDefaultScopes	Loại:  boolean Cho biết lựa chọn scopes sẽ thay thế các phạm vi API Nhúng mặc định hay thêm vào các phạm vi đó. Việc chỉ định false (mặc định) sẽ thêm vào các phạm vi mặc định và việc chỉ định true sẽ thay thế các phạm vi đó bằng các phạm vi được chỉ định bởi tuỳ chọn scopes. Giá trị phạm vi mặc định là:['https://www.googleapis.com/auth/analytics.readonly']. Lưu ý: việc xác thực qua API Nhúng yêu cầu quyền truy cập vào hồ sơ cơ bản của người dùng. Không thể ghi đè các phạm vi đó.
serverAuth.access_token	Loại:  string Nếu đã có mã truy cập hợp lệ, bạn có thể chuyển trực tiếp mã đó vào phương thức cấp phép và người dùng sẽ không bị nhắc cấp phép. Để biết chi tiết về cách truy xuất mã truy cập, hãy xem tài liệu về OAuth 2.0.

Sự kiện
signIn	Đối số: Không có Được kích hoạt khi người dùng đã đăng nhập thành công.
signOut	Đối số: Không có Được kích hoạt khi người dùng đã đăng xuất thành công.
needsAuthorization	Đối số: Không có Khi gọi phương thức gapi.analytics.auth.authorize, hệ thống sẽ kiểm tra ban đầu để xem người dùng hiện có đăng nhập hay không. Nếu người dùng chưa đăng nhập, thì sự kiện này sẽ được kích hoạt để cho biết rằng người dùng cần được uỷ quyền thêm.
error	Đối số:  response Được kích hoạt khi có lỗi xảy ra trong quá trình xác thực. Nếu bạn muốn nhận thông báo lỗi qua đối tượng phản hồi, thông báo lỗi sẽ nằm tại response.error.message.

Sự kiện không dùng nữa
success	Đối số:  response Sự kiện này tồn tại với khả năng tương thích ngược và có thể bị xoá trong phiên bản sau này. Thay vào đó, hãy sử dụng sự kiện signIn.

Ví dụ:

// Standard client-side authorization.

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

gapi.analytics.auth.on('signIn', function() {
  console.log(gapi.analytics.auth.getUserProfile());
});

// Authorization using an access token obtained server-side.
// You do not need to register an event handler because
// authorization happens immediately.

gapi.analytics.auth.authorize({
  serverAuth: {
    access_token: 'XXXXXX'
  }
});

Lưu ý: hoạt động uỷ quyền sẽ diễn ra ngay lập tức khi bạn sử dụng serverAuth.access_token, do đó bạn không cần đăng ký trình xử lý sự kiện.

Lưu ý quan trọng: Khi sử dụng serverAuth.access_token, bạn có trách nhiệm phải đảm bảo mã thông báo này hợp lệ và chưa hết hạn. Để biết thông tin chi tiết về cách làm mới mã truy cập đã hết hạn, hãy xem tài liệu về OAuth 2.0.

Dữ liệu

gapi.analytics.report.Data

Hàm dựng
Data(options:Object)	Thành phần Dữ liệu cho phép bạn truy vấn API Báo cáo chính của Google Analytics và nhận lại kết quả.

Tùy chọn
query	Loại:  Object Đối tượng chứa tham số truy vấn từ API Báo cáo chính. Các giá trị mặc định sau đây được dùng ngoài các giá trị mặc định thông thường do API cung cấp: { 'start-date': '7daysAgo', 'end-date': 'yesterday }

Phương thức kế thừa
get
set
execute
on
once
off
emit

Sự kiện
success	Đối số:  response Được kích hoạt khi truy vấn đã hoàn tất thành công.
error	Đối số:  response Được kích hoạt khi có lỗi xảy ra trong quá trình truy vấn. Nếu bạn muốn nhận thông báo lỗi qua đối tượng phản hồi, thông báo lỗi sẽ nằm tại response.error.message.

Ví dụ:

var report = new gapi.analytics.report.Data({
  query: {
    ids: 'ga:XXXX',
    metrics: 'ga:sessions',
    dimensions: 'ga:city'
  }
});

report.on('success', function(response) {
  console.log(response);
});

report.execute();

DataChart

gapi.analytics.googleCharts.DataChart

Hàm dựng
DataChart(options:Object)	DataChart gói một biểu đồ chuẩn của Google và một thành phần Dữ liệu để bạn có thể dễ dàng tạo hình ảnh từ truy vấn mà không cần phải tự liên kết các biểu đồ đó với nhau.

Tùy chọn
query	Loại:  Object Xem tuỳ chọn truy vấn thành phần dữ liệu.
chart	Loại:  Object Xem bên dưới để biết thông tin chi tiết về từng tuỳ chọn biểu đồ.
chart.container	Loại:  string|HTMLElement Mã của một phần tử HTML trong DOM sẽ lưu trữ DataChart. Bạn cũng có thể chuyển tham chiếu đến chính phần tử đó.
chart.type	Loại:  string Loại biểu đồ. Các tuỳ chọn có thể là: LINE, COLUMN, BAR, TABLE và GEO.
chart.options	Loại:  Object Bất kỳ lựa chọn nào có thể được chuyển đến đối tượng Google Chart tương ứng.

Phương thức kế thừa
get
set
execute
on
once
off
emit

Sự kiện
success	Đối số:  result Được kích hoạt khi truy vấn đã hoàn tất thành công và biểu đồ đã hiển thị đầy đủ. result.chart – phiên bản của Google Biểu đồ. result.data – phản hồi báo cáo ở định dạng tham số dữ liệu. result.dataTable – thực thể DataTable được tạo từ đối tượng result.data. result.response – đối tượng phản hồi API thô.
error	Đối số:  response Được kích hoạt khi xảy ra lỗi trong quá trình truy vấn hoặc hiển thị. Nếu bạn muốn nhận thông báo lỗi qua đối tượng phản hồi, thông báo lỗi sẽ nằm tại response.error.message.

Ví dụ:

var chart = new gapi.analytics.googleCharts.DataChart({
  query: {
    ids: 'ga:XXXX',
    metrics: 'ga:sessions',
    dimensions: 'ga:date'
  },
  chart: {
    type: 'LINE',
    container: 'line-chart',
    options: {
      title: 'Sessions over the past week.',
      fontSize: 12
    }
  }
});
chart.on('success', function(response) {
  // response.chart : the Google Chart instance.
  // response.data : the Google Chart data object.
});

chart.execute();

ViewSelector

gapi.analytics.ViewSelector

Hàm dựng
ViewSelector(options:Object)	Thành phần ViewSelector cho phép bạn chọn tài khoản, tài sản và chế độ xem qua trình đơn thả xuống.

Tùy chọn
container	Loại:  string|HTMLElement Mã của phần tử HTML trong DOM sẽ lưu trữ ViewSelector. Bạn cũng có thể chuyển tham chiếu đến chính phần tử đó.

Phương thức kế thừa
get
set
execute
on
once
off
emit

Thuộc tính thực thể
ids	Loại:  string Mã bảng duy nhất của biểu mẫu ga:XXXX, trong đó XXXX là mã chế độ xem (hồ sơ) Analytics.

Sự kiện
change	Đối số:  ids Được kích hoạt bất cứ khi nào người dùng chọn một chế độ xem mới trên trình đơn thả xuống. Thuộc tính này cũng được kích hoạt khi phiên bản ViewSelector được hiển thị lần đầu tiên và khi chế độ xem mặc định được hiển thị.

Ví dụ:

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

viewSelector.on('change', function(ids) {
  console.log(ids);
});

viewSelector.execute();

Phương thức thành phần dùng chung

Phương thức
set(options)	trả về: this Đặt hoặc cập nhật các tuỳ chọn cấu hình của thành phần (bạn cũng có thể thực hiện việc này tại thời điểm tạo trong hàm khởi tạo).
get()	trả về: Object Trả về các tuỳ chọn cấu hình hiện tại của một thành phần.
execute()	trả về: this Gọi hành động chính của thành phần đó. Thao tác này thường hiển thị nội dung nào đó trên trang hoặc chạy một báo cáo (hoặc cả hai).
on(event, handler)	trả về: this Đăng ký một hàm để được gọi khi thành phần phát ra sự kiện được chỉ định.
once(event, handler)	trả về: this Đăng ký một hàm để chỉ gọi vào lần xuất hiện tiếp theo của sự kiện được chỉ định. Sau khi trình xử lý chạy sau khi tự động huỷ đăng ký.
off(opt_event, opt_handler)	trả về: undefined Xoá một trình xử lý sự kiện khỏi một thành phần. Nếu không có trình xử lý nào được truyền, thì thao tác này sẽ xoá tất cả trình xử lý cho sự kiện đã chuyển. Nếu không có sự kiện nào được thông qua, thì thao tác này sẽ xoá tất cả trình xử lý cho mọi sự kiện.
emit(event, ...opt_args)	trả về: undefined Phát ra một sự kiện. Bạn có thể tuỳ ý chỉ định các đối số để truyền đến bất kỳ trình xử lý đã đăng ký nào.

set

Đặt hoặc cập nhật các tuỳ chọn cấu hình của thành phần (bạn cũng có thể thực hiện việc này tại thời điểm tạo trong hàm khởi tạo).

Cách sử dụng

component.set(options);

Tham số

Tên	Loại	Nội dung mô tả
options	Object	Các lựa chọn cấu hình cho thành phần này. Các lựa chọn đã chọn sẽ được hợp nhất với các lựa chọn hiện có.

Giá trị trả về

this – Thực thể của thành phần.

---

get

Trả về các tuỳ chọn cấu hình hiện tại của một thành phần.

Giá trị trả về

Object – Các tuỳ chọn cấu hình hiện tại của thành phần.

---

execute()

Gọi hành động chính của thành phần đó. Thao tác này thường hiển thị nội dung nào đó trên trang hoặc chạy một báo cáo (hoặc cả hai).

Giá trị trả về

this – Thực thể của thành phần.

---

on(event, handler)

Đăng ký một hàm để được gọi khi thành phần phát ra sự kiện được chỉ định.

Tham số

Tên	Loại	Nội dung mô tả
event	string	Tên của sự kiện.
handler	Function	Hàm sẽ được gọi khi sự kiện xảy ra. (Xem từng tài liệu tham khảo sự kiện để biết thông tin chi tiết về thông số.)

Giá trị trả về

this – Thực thể của thành phần.

---

once(event, handler)

Đăng ký một hàm để chỉ gọi vào lần xuất hiện tiếp theo của sự kiện được chỉ định. Sau khi trình xử lý chạy sau khi tự động huỷ đăng ký.

Tham số

Tên	Loại	Nội dung mô tả
event	string	Tên của sự kiện.
handler	Function	Hàm sẽ được gọi khi sự kiện xảy ra. (Xem từng tài liệu tham khảo sự kiện để biết thông tin chi tiết về thông số.)

Giá trị trả về

this – Thực thể của thành phần.

---

off(opt_event, opt_handler)

Xoá một trình xử lý sự kiện khỏi một thành phần. Nếu không có trình xử lý nào được truyền, thì thao tác này sẽ xoá tất cả trình xử lý cho sự kiện đã chuyển. Nếu không có sự kiện nào được thông qua, thì thao tác này sẽ xoá tất cả trình xử lý cho mọi sự kiện.

Tham số

Tên	Loại	Nội dung mô tả
opt_event	string	Tên của sự kiện. Nếu không có sự kiện nào được chỉ định, thì mọi trình xử lý cho mọi sự kiện sẽ bị xoá. Không bắt buộc.
opt_handler	Function	Tham chiếu đến trình xử lý hàm cần xoá. Nếu không có hàm nào được truyền, thì mọi trình xử lý sẽ bị xoá. Không bắt buộc.

Giá trị trả về

undefined

---

emit(event, ...opt_args)

Phát ra một sự kiện. Bạn có thể tuỳ ý chỉ định các đối số để truyền đến bất kỳ trình xử lý đã đăng ký nào.

Tham số

Tên	Loại	Nội dung mô tả
event	string	Tên của sự kiện.
...opt_args	*	Các đối số không bắt buộc sẽ được truyền đến bất kỳ trình xử lý sự kiện nào đã đăng ký.

Giá trị trả về

undefined