Hướng dẫn các hàm của smart script

Chỉ cần được thiết lập theo đúng yêu cầu của nhà quảng cáo, smart script có thể ghi nhận chính xác phân bổ web-to-app. Tuy nhiên, nhà phát triển vẫn có thể chỉnh sửa smart script nếu cần. Phần dưới đây cung cấp các thuộc tính và hàm của script, cũng như ví dụ minh họa

Các hàm của Smart script

Thiết lập mức ghi nhật ký

Sử dụng hàm setLogLevel để thiết lập mức ghi nhật ký trong console của trình duyệt (nếu cần). Gọi hàm này trước khi gọi hàm createLink. Đối số gồm debug, warn, error hoặc none. Giá trị mặc định là debug.

AdjustSmartScript.setLogLevel('warn')

Tạo liên kết

Sử dụng hàm createLink function để tạo liên kết Adjust chứa các thuộc tính cụ thể của đối tượng mapping.

const mapping = { /* mapping object properties */ }
AdjustSmartScript.createLink(mapping)

Xem phiên bản script

Sử dụng hàm getVersion để kiểm tra phiên bản smart script.

AdjustSmartScript.getVersion()

Các thuộc tính của đối tượng mapping

Bạn cần truyền đối tượng mapping cho phương thức createLink. Bạn PHẢI xác định các thuộc tính sau của đối tượng mapping.

defaultLinkToken (string)

Link token được sử dụng khi không có network link token nào khả dụng hoặc không có cấu hình mạng quảng cáo nào được cung cấp.

campaign (object)

Đối tượng chứa thông tin campaign.

adgroup (object)

Đối tượng chứa thông tin adgroup.

creative (object)

Đối tượng chứa thông tin creative.

Các đối tượng campaign, adgroup và creative PHẢI chứa các thuộc tính sau:

in (string | string[])

Chuỗi hoặc mảng chuỗi là key trong chuỗi truy vấn tìm kiếm URL được dùng làm tên campaign, adgroup hoặc creative.

Nếu mảng được truyền đi, thì script sẽ tìm tên trong tham số GET và truyền tất cả tên (nếu có) cho hàm transform. Nếu tìm không thấy tên, thì script sẽ lấy giá trị đầu tiên không rỗng làm tên campaign, adgroup hoặc creative.

Bạn CÓ THỂ cung cấp thêm các thuộc tính sau:

transform (function)

Hàm được gọi khi có giá trị in. Hàm này trả về giá trị chuỗi, cho biết tên campaign, adgroup hoặc creative. Nếu transform không trả về chuỗi hoặc cảnh báo lỗi, thì script sẽ lấy giá trị đầu tiên không rỗng làm tên campaign, adgroup hoặc creative.

defaultValue (string)

Được sử dụng khi hàm transform không tìm thấy giá trị in.

Nếu triển khai deep linking, thì bạn PHẢI thêm các tham số sau vào đối tượng mapping.

domain (string)

Tên miền thương hiệu.

Bạn có thể chọn tên miền thương hiệu nếu bạn chưa triển khai deep linking. Nếu bạn không chọn tên miền nào, thì liên kết app.adjust.com sẽ được tạo.

iosAppSchema (string)

iOS app scheme.

androidAppSchema (string)

Android app scheme.

Nếu triển khai deep link, thì bạn CÓ THỂ bổ sung các tham số sau.

iosDeeplinkPath (string)

Đường dẫn của iOS deep link.

androidDeeplinkPath (string)

Đường dẫn của Android deep link.

Bạn CÓ THỂ bổ sung các tham số sau cho đối tượng mapping.

inputUrl (string)

URL của landing page trên mobile web. Nếu bạn không điền giá trị nào ở đây, thì script sẽ sử dụng giá trị window.location.href làm URL.

label (object`) Tham số này cho phép bạn gửi dữ liệu tùy chỉnh. Tham khảo Help Center để biết thêm thông tin.

networks (object)

Đối tượng key-value có chứa thông tin mạng quảng cáo.

Đối tượng networks PHẢI chứa ít nhất một key là tên network. Các key sau được hỗ trợ:

• Meta
• google_ads

Giá trị PHẢI là đối tượng chứa các thuộc tính sau:

linkToken (string)

Link token của network đã được xác định trong key.

customParameters (object)

Đối tượng chứa thông tin tham số tùy chỉnh.

Đối tượng customParameters PHẢI chứa các thuộc tính sau:

in (string | string[])

Chuỗi hoặc mảng chuỗi là key của chuỗi truy vấn tìm kiếm URL được sử dụng làm tên tùy chỉnh.

Nếu mảng được truyền đi, thì script sẽ tìm tên trong tham số GET và truyền tất cả tên (nếu có) cho hàm transform. Nếu tìm không thấy tên, thì script sẽ lấy giá trị đầu tiên không rỗng làm tên tùy chỉnh.

out (string)

Chuỗi cho biết tên của tham số tùy chỉnh được ghi trong liên kết Adjust.

Bạn CÓ THỂ cung cấp thêm các thuộc tính sau:

transform (function)

Hàm được gọi khi có giá trị in. Hàm trả về giá trị chuỗi là tên tùy chỉnh. Nếu hàm transform không trả về chuỗi hoặc cảnh báo lỗi, thì giá trị đầu tiên không rỗng sẽ được dùng làm tên tùy chỉnh.

defaultValue (string)

Được sử dụng khi hàm transform không tìm thấy giá trị in.

Ví dụ

const mapping = {
  inputUrl: "https://www.landing.com?campaign_name=Summer2024&ad_group=SomeGroup",
  defaultLinkToken: "abcd123",
  campaign: { in: "campaign_name" },
  adgroup: { in: "ad_group" },
  creative: { in: "element" }
}
const link = AdjustSmartScript.createLink(mapping);
console.log(link)
// expected output: https://app.adjust.com/abcd123?campaign=Summer2024&adgroup=SomeGroup

const mapping = {
  defaultLinkToken: "abcd1234",
  networks: {
    meta: { linkToken: 'efgh5678'},
    google_ads: { linkToken: 'ijkl9012' }
  },
  campaign: { in: "c" },
  adgroup: { in: "a" },
  creative: { in: "cr" }
}
const link1 = AdjustSmartScript.createLink({
  ...mapping,
  inputUrl: "https://www.landing.com?c=Summer2024&a=SomeGroup&cr=banner&gclid=CLICK_ID"
});
console.log(link1)
// expected output: https://app.adjust.com/ijkl9012?gclid=CLICK_ID&campaign=Summer2024&adgroup=SomeGroup&creative=banner
const link2 = AdjustSmartScript.createLink({
  ...mapping,
  inputUrl: "https://www.landing.com?c=Winter2025&a=AnotherGroup&cr=image&fbclid=FB_CLICK_ID"
});
console.log(link2)
// expected output: https://app.adjust.com/efgh5678?fbclid=FB_CLICK_ID&campaign=Winter2025&adgroup=AnotherGroup&creative=image

const mapping = {
  inputUrl: "https://www.landing.com?utm_content=logo_image&utm_medium=social&utm_source=some-source&utm_campaign=new_campaign",
  defaultLinkToken: "example123",
  domain: "branded.go.link",
  campaign: {
    in: "utm_campaign",
    defaultValue: "dummy-name"
  },
  adgroup: {
    in: ["utm_source", "utm_medium"],
    transform: function(values) { return (values[0] && values[1]) ? `${values[0]}: ${values[1]}` : undefined; }
  },
  creative: {
    in: "utm_content",
    transform: function(values) { return values[0] ? `ad_${values[0]}` : 'ad_default' }
  }
}
const link = AdjustSmartScript.createLink(mapping);
console.log(link)
// expected output: https://branded.go.link?adj_token=example123&adj_campaign=new_campaign&adj_adgroup=some-source%3A%20social&adj_creative=ad_logo_image

const mapping = {
  inputUrl: "https://www.landing.com?user_id=id&cr=logo_image&ad=some_adset&c=new_campaign&product=my_product",
  domain: "example.go.link",
  defaultLinkToken: "abcd1234",
  campaign: { in: "c" },
  adgroup: { in: "ad" },
  creative: { in: "cr" },
  customParameters: [{
    in: ['product', 'user_id'],
    out: 'ref_code',
    transform: function (values) {
      const product = values[0]
      const userId = values[1]
      if (product && userId) {
        return `${userId}+${product}`
      }
      return ''
    }
  }]
}
const link = AdjustSmartScript.createLink(mapping);
console.log(link)
// expected output: https://example.go.link?adj_token=abcd1234&adj_campaign=new_campaign&adj_adgroup=some_adset&adj_creative=logo_image&ref_code=id%2Bmy_product

const mapping = {
  inputUrl: "https://www.landing.com?&cr=logo_image&ad=some_adset&c=new_campaign",
  domain: "example.go.link",
  defaultLinkToken: "abcd1234",
  campaign: { in: "c" },
  adgroup: { in: "ad" },
  creative: { in: "cr" },
  iosAppSchema: "app",
  iosDeeplinkPath: "path/to/screen",
}
const link = AdjustSmartScript.createLink(mapping);
console.log(link)
// expected output: https://example.go.link/path/to/screen?adjust_t=abcd1234&adj_campaign=new_campaign&adj_adgroup=some_adset&adj_creative=logo_image

const mapping = {
  inputUrl: "https://www.landing.com?&cr=logo_image&ad=some_adset&c=new_campaign",
  domain: "example.go.link",
  defaultLinkToken: "abcd1234",
  campaign: { in: "c" },
  adgroup: { in: "ad" },
  creative: { in: "cr" },
  androidAppSchema: "scheme",
  androidDeeplinkPath: "some/path",
}
const link = AdjustSmartScript.createLink(mapping);
console.log(link)
// expected output: https://example.go.link/some/path?adjust_t=abcd1234&adj_campaign=new_campaign&adj_adgroup=some_adset&adj_creative=logo_image

const mapping = {
  inputUrl: "https://www.landing.com?&cr=logo_image&ad=some_adset&c=new_campaign",
  domain: "example.go.link",
  defaultLinkToken: "abcd1234",
  campaign: { in: "c" },
  adgroup: { in: "ad" },
  creative: { in: "cr" },
  androidAppSchema: "scheme",
  androidDeeplinkPath: "some/path",
  iosAppSchema: "app",
  iosDeeplinkPath: "path/to/screen",
}
const link = AdjustSmartScript.createLink(mapping);
console.log(link)
// expected output: https://hello.go.link/path/to/screen?adjust_t=abcd1234&adjust_deeplink=scheme%3A%2F%2Fsome%2Fpath&adj_campaign=new_campaign&adj_adgroup=some_adset&adj_creative=logo_image

Kiểm thử Smart script

Smart script lưu nhật ký vào console của trình duyệt. Adjust khuyến nghị bạn nên kiểm thử hiệu quả hoạt động của script, đảm bảo script tạo đúng liên kết.

1. Mở trình duyệt, truy cập Developer Tools console.
2. Mở web page mà bạn sử dụng để triển khai Smart script.
3. Nếu không tìm thấy nhật ký nào có prefix là [adjust-smart-script], làm mới trang. Nếu vẫn không thấy, kiểm tra để đảm bảo rằng:
   • Trong code bạn không gọi các hàm ngăn ghi nhật ký như AdjustSmartScript.setLogLevel('error') hay AdjustSmartScript.setLogLevel('none').
   • Trong code bạn đã gọi hàm AdjustSmartScript.createLink(params).

Sử dụng các giá trị khác nhau của thuộc tính inputUrl để kiểm thử smart script ở nhiều trường hợp sử dụng. Ví dụ: Nếu bạn đang chạy chiến dịch trên Meta, đồng thời hy vọng có người dùng chủ động truy cập landing page không qua quảng cáo (người dùng tự nhiên), thì bạn có thể tạo URL chứa tham số chiến dịch và tham số Meta, rồi tạo thêm URL khác không chứa các loại tham số này.

Ví dụ về nhật ký:

[adjust-smart-script]: No networks configured
[adjust-smart-script]: Use defaultLinkToken to create adjust link
[adjust-smart-script]: Found value for campaign is new_campaign
[adjust-smart-script]: Found value for adgroup is some_adset
[adjust-smart-script]: Found value for creative is logo_image
[adjust-smart-script]: Transformed value for ref_code is id+my_product
[adjust-smart-script]: Misconfigured deep link: no valid androidAppSchema provided