Tài liệu tham khảo

Thông số

Nội dung mô tả thông số cấp trang

Bạn chỉ cần chỉ định các thông số này một lần cho mỗi trang. Thông số cấp trang sẽ có hiệu lực đối với tất cả các đơn vị trên trang.

Bắt buộc

Thông số Nội dung mô tả và ví dụ
adPage Bắt buộc khi người dùng chuyển đến trang kết quả tiếp theo hoặc trang kết quả trước đó.

Thông số adPage chỉ định trang kết quả mà quảng cáo đang được hiển thị trên đó. Thông số này được sử dụng khi người dùng điều hướng qua trang đầu tiên của kết quả tìm kiếm. Ví dụ: nếu 5 quảng cáo được yêu cầu và tham số adPage được đặt thành 2, thì quảng cáo được trả về trong số 5 quảng cáo sẽ xuất hiện trên trang thứ hai.

pubId Bắt buộc
Đây là mã ứng dụng khách AdSense của bạn. pubId là một phần của client-ID, đứng sau "partner-". Ví dụ: nếu client-ID là "partner-test-property", thì pubId sẽ là "test-property". Đây là giao thức chuẩn cho CSA.

Ví dụ: 

'pubId' : 'test-property'
query Bắt buộc, ngoại trừ trên phần Nội dung tìm kiếm có liên quan trên trang Nội dung.
Đây là cụm từ tìm kiếm do người dùng nhập. Không được mã hoá giá trị của tham số truy vấn.

Lưu ý: Việc sử dụng thông số này trên phần Nội dung tìm kiếm có liên quan trên các trang Nội dung sẽ dẫn đến kết quả không mong muốn.

Ví dụ: 

'query' : 'flowers'
 
'query' : 'black & decker'
 
'query' : myQuery // myQuery is a variable containing the search query
resultsPageBaseUrl Bắt buộc khi có các đơn vị tìm kiếm có liên quan trên trang.
Chỉ định URL của trang kết quả tìm kiếm chứa cụm từ tìm kiếm là cụm từ tìm kiếm có liên quan mà người dùng đã nhấp vào. resultsPageBaseUrl có thể bao gồm các thông số riêng, ngoại trừ cụm từ tìm kiếm sẽ được thêm tự động.

Ví dụ: 

'resultsPageBaseUrl' : 'http://www.example.com/search?a=v1&b=v2'
relatedSearchTargeting Bắt buộc khi có các đơn vị tìm kiếm có liên quan trên trang.
Thông số này là bắt buộc khi bạn yêu cầu đơn vị tìm kiếm có liên quan. Thuộc tính này kiểm soát loại trải nghiệm Nội dung tìm kiếm có liên quan sẽ hiển thị, tuỳ thuộc vào ngữ cảnh trang:
  • 'content' Sử dụng tuỳ chọn này cho phần Nội dung tìm kiếm có liên quan trên các trang Nội dung (ví dụ: bài viết, bài đăng trên blog).
  • 'query' Sử dụng lựa chọn này riêng cho tính năng Cụm từ tìm kiếm có liên quan trên trang kết quả tìm kiếm.

Lưu ý: Theo mặc định, tham số trang relatedSearchTargeting sẽ tự động được đặt thành "query". Tuy nhiên, điều quan trọng cần lưu ý là giá trị mặc định này được thiết kế riêng cho chỉ các trang kết quả tìm kiếm (Cụm từ tìm kiếm có liên quan trên Tìm kiếm). Nếu đang sử dụng nội dung tìm kiếm có liên quan trên bất kỳ loại trang nào khác (ví dụ: bài viết, bài đăng trên blog), bạn phải đặt rõ ràng tham số này thành "content".

Lưu ý: Bạn phải tuân theo các nguyên tắc sau khi sử dụng thông số này:

  • Một số tính năng tìm kiếm có liên quan có thể được bật hoặc tắt tuỳ thuộc vào giá trị của tham số trang này.
  • Việc trình bày sai loại trang hoặc dựa vào chế độ cài đặt "truy vấn" mặc định cho tham số relatedSearchTargeting trên các trang không phải trang kết quả tìm kiếm được coi là vi phạm các hướng dẫn bằng văn bản này.
  • Google có thể xác minh định kỳ độ chính xác của giá trị này, bất kể giá trị này được đặt theo cách thủ công hay sử dụng giá trị mặc định.

Ví dụ:

'relatedSearchTargeting' : 'content'
 
'relatedSearchTargeting' : 'query'
styleId Bắt buộc
Chỉ định mã nhận dạng của kiểu quảng cáo đi kèm kết quả tìm kiếm tuỳ chỉnh áp dụng cho các đơn vị quảng cáo hoặc đơn vị tìm kiếm có liên quan trên trang. Tìm hiểu thêm về cách sử dụng kiểu quảng cáo đi kèm kết quả tìm kiếm tuỳ chỉnh. Xin lưu ý rằng khi đặt styleId cho một yêu cầu, quảng cáo hoặc nội dung tìm kiếm có liên quan sẽ được hiển thị với kiểu quảng cáo đó, và các thông số của kiểu cũ sẽ bị bỏ qua. Nếu styleId không được chỉ định trong yêu cầu, thì kiểu mặc định của hệ thống sẽ hiển thị.

Ví dụ: 

'styleId': '1234567890'

Không bắt buộc

Thông số Nội dung mô tả và ví dụ
linkTarget Không bắt buộc
Chỉ định xem quảng cáo sẽ mở ra trong cùng một cửa sổ hay trong một cửa sổ mới khi người dùng nhấp vào. Giá trị mặc định là '_top'. Bạn cũng có thể dùng thông số này ở cấp đơn vị.
  • '_top' Mở trong cùng một cửa sổ.
  • '_blank' Mở trong một cửa sổ mới.

Ví dụ: 

'linkTarget' : '_blank'
referrerAdCreative Không bắt buộc
Nếu sau khi nhấp vào một quảng cáo hoặc đường liên kết thuộc quyền kiểm soát của bạn trên một trang web khác, người dùng được chuyển đến trang nội dung của bạn và trang đó có chứa một Nội dung tìm kiếm có liên quan cho đơn vị Nội dung, thì bạn cần đặt thông số này thành nguyên văn văn bản mẫu quảng cáo của quảng cáo hoặc đường liên kết đó.

Bạn phải tuân theo các nguyên tắc sau khi sử dụng thông số này:

  • Thông số này chỉ được cung cấp trên Nội dung tìm kiếm có liên quan cho yêu cầu Nội dung, và nó sẽ bị bỏ qua trong tất cả các yêu cầu khác.
  • Tham số này chỉ được dùng cho lưu lượng truy cập mà bạn cố ý lấy từ các trang web khác và không được dùng cho lưu lượng truy cập tự nhiên.
  • Thông số này phải bao gồm dòng tiêu đề, nội dung mô tả và/hoặc mọi từ ngữ khác trong mẫu quảng cáo hoặc mẫu quảng cáo đường liên kết.
  • Việc bỏ qua các giá trị khỏi mẫu quảng cáo hoặc mẫu quảng cáo đường liên kết (hoặc thêm các giá trị khác) được coi là vi phạm các hướng dẫn bằng văn bản này.
  • Thông số này không phân biệt chữ hoa chữ thường.
  • Thông số này chấp nhận phương thức mã hoá UTF-8 hợp lệ; có hỗ trợ ký tự unicode / dấu phụ.
  • Google có thể sử dụng hoặc bỏ qua thông số bạn gửi. Khi được sử dụng, thông số này có thể ảnh hưởng đến việc lựa chọn và xếp hạng các từ khoá.

Lưu ý: Bạn bắt buộc phải sử dụng tham số này khi sử dụng tham số terms.

Ví dụ: 

'referrerAdCreative': 'search for ads related to dental implants'

'referrerAdCreative': 'The Early Signs of Psoriatic Arthritis'
resultsPageQueryParam Không bắt buộc
Chỉ định tên của tham số URL cho cụm từ tìm kiếm trên trang kết quả tìm kiếm. Giá trị mặc định là 'q' nếu không được chỉ định.

Ví dụ: 

'resultsPageQueryParam' : 'query'
terms Không bắt buộc
Thông số này cho phép bạn cung cấp một danh sách được phân tách bằng dấu phẩy gồm các cụm từ tìm kiếm có liên quan của riêng bạn sẽ được trả về cùng với một yêu cầu tìm kiếm có liên quan, mặc dù Google có thể hoặc không thể sử dụng các cụm từ được cung cấp tại đây.

Lưu ý: Khi sử dụng tham số này, bạn cũng bắt buộc phải sử dụng referrerAdCreative và relatedSearchTargeting, đồng thời phải đặt thành "content".

Ví dụ: 

'terms' : 'cars rental, flight ticket'
ignoredPageParams Không bắt buộc
Chỉ định danh sách tham số URL cho một trang nội dung có đơn vị Tìm kiếm có liên quan cho nội dung mà bạn có thể bỏ qua mà không ảnh hưởng đến nội dung cốt lõi hoặc trải nghiệm người dùng.

Lưu ý: Trước khi các cụm từ tìm kiếm có liên quan có thể xuất hiện trên trang web của bạn, Google cần thu thập thông tin trên các trang của bạn để đảm bảo các cụm từ đó phù hợp với bối cảnh. Khi một trang chưa được trình thu thập thông tin của AdSense thu thập thông tin hoặc bị chặn thu thập thông tin (ví dụ: do tệp robots.txt), chúng tôi sẽ không hiển thị cụm từ tìm kiếm có liên quan được đề xuất mà bạn cung cấp cho Google.

Sản phẩm Nội dung tìm kiếm có liên quan dựa vào hệ thống thu thập dữ liệu nội dung của Google để lập chỉ mục các trang và tạo cụm từ tìm kiếm có liên quan. URL của trang nội dung chứa các tham số truy vấn (như biến theo dõi, mã nhận dạng người dùng, mã phiên hoặc các giá trị nhận dạng động khác) có thể ảnh hưởng đến khả năng của trình thu thập thông tin trong việc đánh giá nội dung cốt lõi trên trang và có thể dẫn đến cụm từ tìm kiếm có liên quan không chính xác hoặc không liên quan. Tham số trang này hướng dẫn trình thu thập dữ liệu của Google bỏ qua các tham số không cần thiết này, đảm bảo việc lập chỉ mục nội dung phù hợp và giảm tải thu thập dữ liệu không cần thiết. Điều này giúp Google nhận dạng tốt hơn một trang đã được thu thập dữ liệu và bắt đầu hiển thị các cụm từ được đề xuất (của cả Google và đối tác, nếu đủ điều kiện).

Bạn phải tuân theo các nguyên tắc sau khi sử dụng thông số này:

  • Thông số này chỉ được cung cấp trên Nội dung tìm kiếm có liên quan cho yêu cầu Nội dung, và nó sẽ bị bỏ qua trong tất cả các yêu cầu khác.
  • Giá trị của thông số này phải là danh sách các tham số URL được phân tách bằng dấu phẩy có thể xuất hiện khi bất kỳ người dùng nào chuyển đến trang nội dung.
  • Mã này phân biệt chữ hoa chữ thường.
  • Khi bất kỳ tham số URL nào trong danh sách này bị xoá khỏi URL của trang nội dung, nội dung, giao diện hoặc trải nghiệm người dùng của trang sẽ không bị ảnh hưởng đáng kể.
  • Việc đưa một tham số URL có tác động đáng kể đến nội dung, giao diện hoặc trải nghiệm người dùng của trang được coi là vi phạm các hướng dẫn bằng văn bản này.
  • Google có thể định kỳ xác minh hiệu quả của việc bỏ qua các tham số URL đã cung cấp.

Ví dụ:
Người dùng truy cập vào một trang nội dung và URL của trang đó là: 

http://example.com/content?utm_medium=social&page_id=123&click_id=456
 Cung cấp các tham số URL có thể bỏ qua sau đây: 
'ignoredPageParams' : 'utm_medium,click_id,session_ref'
 Xem URL của trang nội dung là: 
http://example.com/content?page_id=123

Cài đặt cấu hình

Thông số Nội dung mô tả và ví dụ
adsafe Không bắt buộc
Chỉ định quy tắc lọc mà Google cần áp dụng cho những quảng cáo khớp với cụm từ tìm kiếm. Sau đây là các chế độ cài đặt hợp lệ cho adsafe và tác động của từng giá trị đến quảng cáo trả về:
  • 'high' Trả về quảng cáo an toàn cho gia đình. Không trả về quảng cáo có nội dung khiêu dâm người lớn hoặc không an toàn cho gia đình.
  • 'medium' Trả về quảng cáo an toàn cho gia đình và không an toàn cho gia đình. Không trả về quảng cáo có nội dung khiêu dâm người lớn.
  • 'low' Trả về tất cả các loại quảng cáo.

Theo mặc định, adsafe được đặt thành cao.

Ví dụ: 

'adsafe': 'medium'
adtest Không bắt buộc
Thông số adtest được dùng để cho biết rằng một yêu cầu quảng cáo là thử nghiệm. Khi thông số adtest có giá trị on, Google sẽ coi yêu cầu đó là thử nghiệm và không tính số lượt hiển thị quảng cáo hoặc theo dõi kết quả lượt nhấp.

Khi tham số adtest có giá trị on, bạn sẽ không tạo ra doanh thu.

Những yêu cầu quảng cáo có tham số adtest được đặt thành on đến từ một miền chưa được phê duyệt trong thẻ Trang web sẽ trả về quảng cáo có lớp phủ "quảng cáo thử nghiệm" và không thể nhấp vào được.

Bạn có thể sử dụng tham số này khi thử nghiệm, nhưng đừng sử dụng tham số này trong các hệ thống sản phẩm. Nếu không, bạn sẽ không được thanh toán cho những quảng cáo mà bạn hiển thị.

Giá trị mặc định của tham số adtest là tắt.

Ví dụ: 

'adtest' : 'on'
channel Không bắt buộc
Bạn có thể thêm kênh AdSense cho Tìm kiếm để theo dõi hiệu suất của các trang khác nhau. Sử dụng mã nhận dạng kênh duy nhất do bạn tạo trong tài khoản AdSense hoặc do Nhà quản lý tài khoản kỹ thuật của bạn tạo. Tìm hiểu thêm về kênh tại đây.

Các kênh phải được phân tách bằng dấu '+'.

Ví dụ: 

'channel' :  'testA'  
'channel' :  'testA+testB'
hl Không bắt buộc
Thông số này xác định ngôn ngữ mà quảng cáo hoặc nội dung tìm kiếm có liên quan được yêu cầu nên nhắm đến. Giá trị mặc định là en.

Google hỗ trợ tất cả mã ngôn ngữ API AdWords.

Lưu ý: Nhà quảng cáo chỉ định ngôn ngữ mà quảng cáo của họ nhắm đến. Nếu bạn đưa thông số này vào yêu cầu của mình, thì Google sẽ chỉ trả về những quảng cáo được nhắm đến ngôn ngữ đó hoặc được nhắm đến tất cả các ngôn ngữ nhưng không đảm bảo rằng văn bản quảng cáo sẽ xuất hiện bằng ngôn ngữ được chỉ định.

Thông thường, bạn nên đặt tham số hl thành ngôn ngữ chính của trang sẽ gửi thông số này.

Ví dụ: 

'hl' : 'es'
ie Không bắt buộc

Tham số ie đặt lược đồ mã hoá ký tự sẽ được sử dụng để diễn giải chuỗi truy vấn.

Giá trị ie mặc định là utf-8.

Giá trị Tên tiêu chuẩn Ngôn ngữ có liên quan được hỗ trợ
latin1 ISO-8859-1 Tây Âu (tiếng Catalan, tiếng Đan Mạch, tiếng Hà Lan, tiếng Anh, tiếng Phần Lan, tiếng Pháp, tiếng Đức, tiếng Indonesia, tiếng Ý, tiếng Na Uy, tiếng Bồ Đào Nha, tiếng Tây Ban Nha, tiếng Thuỵ Điển)
latin2 ISO-8859-2 Đông Âu (tiếng Croatia, tiếng Séc, tiếng Hungary, tiếng Ba Lan, tiếng Rumani, tiếng Serbia, tiếng Slovak, tiếng Slovenia)
latin3 ISO-8859-3  
latin4 ISO-8859-4 Tiếng Baltic (tiếng Estonia, tiếng Latvia, tiếng Lithuania)
cyrillic ISO-8859-5 Tiếng Bungary, tiếng Nga
arabic ISO-8859-6  
tiếng Hy Lạp ISO-8859-7 Tiếng Hy Lạp
hebrew ISO-8859-8 Tiếng Do Thái
latin5 ISO-8859-9  
latin6 ISO-8859-10 Tiếng Iceland
euc-jp EUC-JP Tiếng Nhật
euc-kr EUC-KR Tiếng Hàn
sjis Shift_JIS Tiếng Nhật
big5 Big5 Tiếng Trung phồn thể
gb GB2312 Tiếng Trung giản thể
utf-8 UTF-8 Tất cả
oe Không bắt buộc

Thông số oe đặt lược đồ mã hoá ký tự mà Google sẽ sử dụng để mã hoá văn bản của quảng cáo. Mặc dù về mặt kỹ thuật đây là thông số không bắt buộc, nhưng bạn nên chuyển một giá trị cho thông số này.

Giá trị oe mặc định là utf-8.

Giá trị Tên tiêu chuẩn Ngôn ngữ có liên quan được hỗ trợ
latin1 ISO-8859-1 Tây Âu (tiếng Catalan, tiếng Đan Mạch, tiếng Hà Lan, tiếng Anh, tiếng Phần Lan, tiếng Pháp, tiếng Đức, tiếng Indonesia, tiếng Ý, tiếng Na Uy, tiếng Bồ Đào Nha, tiếng Tây Ban Nha, tiếng Thuỵ Điển)
latin2 ISO-8859-2 Đông Âu (tiếng Croatia, tiếng Séc, tiếng Hungary, tiếng Ba Lan, tiếng Rumani, tiếng Serbia, tiếng Slovak, tiếng Slovenia)
latin3 ISO-8859-3  
latin4 ISO-8859-4 Tiếng Baltic (tiếng Estonia, tiếng Latvia, tiếng Lithuania)
cyrillic ISO-8859-5 Tiếng Bungary, tiếng Nga
arabic ISO-8859-6  
tiếng Hy Lạp ISO-8859-7 Tiếng Hy Lạp
hebrew ISO-8859-8 Tiếng Do Thái
latin5 ISO-8859-9  
latin6 ISO-8859-10 Tiếng Iceland
euc-jp EUC-JP Tiếng Nhật
euc-kr EUC-KR Tiếng Hàn
sjis Shift_JIS Tiếng Nhật
gb GB2312 Tiếng Trung giản thể
utf-8 UTF-8 Tất cả
ivt Không bắt buộc
Thông số này cho phép bạn cung cấp một boolean để thông báo cho Google rằng bạn muốn cho phép quảng cáo sử dụng cookie chỉ dùng để phát hiện lưu lượng truy cập không hợp lệ và phương pháp lưu trữ cục bộ trên cả lưu lượng truy cập có sự đồng ý và lưu lượng truy cập không có sự đồng ý.
  • true Khi không có thông số này hoặc bạn đặt thông số này thành "true", chúng tôi sẽ đặt cookie chỉ dùng để phát hiện lưu lượng truy cập không hợp lệ và chỉ sử dụng bộ nhớ cục bộ cho lưu lượng truy cập có sự đồng ý.
  • false Khi bạn đặt thông số này thành "false", chúng tôi sẽ đặt cookie chỉ dùng để phát hiện lưu lượng truy cập không hợp lệ và sử dụng bộ nhớ cục bộ trên cả lưu lượng truy cập có sự đồng ý và lưu lượng truy cập không có sự đồng ý.

Theo mặc định, IVT được đặt thành true.

Ví dụ: 

'ivt': false

Nội dung mô tả thông số cấp đơn vị

Những thông số này ảnh hưởng đến cách hiển thị các đơn vị quảng cáo riêng lẻ trên một trang cho người dùng. Bạn có thể đặt riêng từng thông số cho từng đơn vị quảng cáo.

Bắt buộc

Thông số Nội dung mô tả và ví dụ
container Bắt buộc
Mã nhận dạng của vùng chứa quảng cáo trống <div> nơi quảng cáo sẽ xuất hiện.

Ví dụ: 

'container' : 'afscontainer1'
maxTop Bắt buộc khi đơn vị quảng cáo nằm phía trên kết quả tìm kiếm.

Dùng tham số này để chỉ định số lượng quảng cáo được hiển thị trên đơn vị quảng cáo hàng đầu.

Lưu ý: Tham số này được dùng thay cho tham số "số". Đơn vị quảng cáo này phải đủ rộng để dòng đầu tiên của quảng cáo không bị che khuất. Việc sử dụng tham số maxTop trên bất kỳ vị trí nào khác trên trang là vi phạm chính sách.

Ví dụ:

'maxTop' : 4
width Bắt buộc
Chỉ định chiều rộng (bằng pixel) cho quảng cáo hoặc đơn vị tìm kiếm có liên quan.

Ví dụ: 

'width' : '700px'
 
'width' : 700

Cài đặt cấu hình

Thông số Nội dung mô tả và ví dụ
adLoadedCallback Không bắt buộc
Chỉ định hàm JavaScript sẽ được gọi khi quảng cáo hoặc nội dung tìm kiếm có liên quan đã tải hoặc khi không có quảng cáo hoặc nội dung tìm kiếm có liên quan nào được phân phát. Bạn nên đặt thông số này thành hàm callback JavaScript mà bạn triển khai để cho phép thực hiện hành động khi lệnh gọi quảng cáo hoàn tất.

Hàm callback này có các thông số sau:

containerName Tên vùng chứa của quảng cáo hoặc đơn vị quảng cáo tìm kiếm có liên quan.
adsLoaded Đặt thành true khi có ít nhất một quảng cáo hoặc cụm từ tìm kiếm có liên quan để hiển thị và đặt thành false khi không có quảng cáo hoặc cụm từ tìm kiếm có liên quan nào được trả về.
isExperimentVariant Đặt thành true nếu một thử nghiệm định kiểu tuỳ chỉnh đang chạy và biến thể của thử nghiệm đó được chọn để hiển thị quảng cáo.
callbackOptions Đối tượng JSON chứa các trường sau:
termPositions: Đối với một khối tìm kiếm có liên quan, hãy bao gồm một map<string,int> của nhà xuất bản cung cấp các cụm từ cho vị trí được lập chỉ mục bắt đầu từ 0 của những cụm từ này trong nội dung phản hồi. Nếu một cụm từ được cung cấp nhưng không được trả về, thì cụm từ đó sẽ không xuất hiện trên bản đồ.

Lưu ý: Vui lòng kiểm tra hàm callback của bạn để đảm bảo hàm này không tạo ra bất kỳ lỗi nào, đặc biệt là những lỗi có thể ảnh hưởng đến việc tải trang của bạn.

Ví dụ về lệnh gọi lại JavaScript: 

var adblock1 = {
  'container' : 'adblock1_div_id',
  'adLoadedCallback' : function(containerName, adsLoaded,
    isExperimentVariant, callbackOptions) {
    if (adsLoaded) {
       try {
         // most likely do nothing
       } catch (e) {
         alert ("Error in callback function");
         // Do something to handle error gracefully
       }
    } else {
       // as you always do when there is no ad coverage from Google
    }
  }
};
number Không bắt buộc
Số lượng quảng cáo sẽ xuất hiện trong đơn vị này. Giá trị mặc định là 2.

Ví dụ: 

'number' : 4
relatedSearches Không bắt buộc
Số lượng cụm từ tìm kiếm có liên quan sẽ xuất hiện trong đơn vị này. Giá trị mặc định là 0 nếu không được chỉ định.

Ví dụ: 

'relatedSearches' : 4