SDK TypeScript

Một gói với sáu điểm vào. Hãy nhập điểm phù hợp với môi trường chạy của bạn, và bản dựng rung cây sẽ để phần còn lại ngoài bundle.

Nơi phát hành

@prodantix/sdk on npm.

Cài đặt

bun add @prodantix/sdk

Các điểm vào

Mỗi đường dẫn con đi kèm bản dựng ESM và CommonJS riêng cùng kiểu dữ liệu riêng. Gốc không phụ thuộc môi trường chạy, các phần còn lại bổ sung thứ mà một môi trường cụ thể cần.

@prodantix/sdk

Client, bộ đánh giá cờ, cùng các giao diện lưu trữ và truyền tải. Không phần nào ở đây chạm vào DOM, nên bạn có thể cung cấp lưu trữ, truyền tải, đồng hồ hay bộ sinh id của riêng mình và chạy ở bất cứ đâu.

import { createClient, MemoryStorage } from '@prodantix/sdk';

const prodantix = createClient({
  apiKey: PRODANTIX_PUBLIC_KEY,
  host: 'https://eu.api.prodantix.com',
  storage: new MemoryStorage(),
});

prodantix.capture('order.completed', { properties: { amount: 4200, currency: 'XAF' } });
await prodantix.flush();

@prodantix/sdk/web

Phần đấu nối trình duyệt đặt trên cùng client đó: lưu trong local storage, gửi bằng beacon khi trang bị ẩn, cùng việc tự động thu pageview và cú nhấp. Phát lại phiên vẫn tắt cho tới khi bạn cung cấp máy chủ phát lại.

import { createWebClient } from '@prodantix/sdk/web';

const prodantix = createWebClient({
  apiKey: PRODANTIX_PUBLIC_KEY,
  host: 'https://eu.api.prodantix.com',
  flagsHost: 'https://api.prodantix.com',
  cookieDomain: 'example.com',
  autocaptureOptions: { clicks: true, pageviews: true },
});

prodantix.identify('user-42', { set: { plan: 'pro' } });

if (await prodantix.isFeatureEnabled('new-checkout')) {
  // ...
}

// Every per-flag read records one $feature_flag_called exposure.
const variant = await prodantix.getVariant('new-checkout');
if (variant?.key === 'treatment') {
  // ...
}

// A flag targeting a cohort reads this user's memberships from the store;
// pass them yourself to skip the lookup.
if (await prodantix.isFeatureEnabledLocal('members', { cohorts: ['<cohort id>'] })) {
  // ...
}

Trên web, id ẩn danh và phiên của khách truy cập nằm trong một cookie bên thứ nhất duy nhất trên miền có thể đăng ký của bạn, nên xyz.com, app.xyz.com và console.xyz.com nhìn thấy cùng một người: lượt ghé trang tiếp thị, lượt đăng ký và phiên đầu tiên trong ứng dụng cùng nằm trên một dòng thời gian ngay khi ứng dụng nhận diện người đó. Id đã nhận diện ở lại local storage theo từng origin và không bao giờ vào cookie, vì mọi host dưới miền đó đều đọc được nó. Miền được tìm bằng cách hỏi trình duyệt, hoặc đặt bằng cookieDomain; trang có các miền con thuộc về những khách thuê khác nhau phải đặt nó thành host của chính mình. Truyền sharedStorage để không ghi cookie nào, chẳng hạn cho tới khi có sự đồng ý, và local storage vẫn là phương án dự phòng khi cookie bị từ chối. Mỗi lượt ghé thăm được cấp một id phiên, thay mới sau ba mươi phút không hoạt động hoặc hai mươi bốn giờ, được gắn vào mọi sự kiện và dùng chung với phát lại phiên.

Cookie không thể vượt qua một tên miền đăng ký được, nên một khách truy cập theo liên kết từ trang này sang trang khác sẽ thành hai khách. Hãy truyền linkedDomains, mặc định để trống, và client sẽ trang trí các liên kết đi tới những tên miền đó, khi click và auxclick, bằng một tham số _pdx mang theo ba thứ: id ẩn danh, id phiên và thời điểm phiên bắt đầu, để cửa sổ ba mươi phút và trần hai mươi bốn giờ tiếp tục qua bước nhảy. Chỉ id ẩn danh đi cùng, không bao giờ là id đã định danh, vì chính nơi đến sẽ tự định danh người đó. Liên kết tới cùng một tên miền đăng ký được, liên kết đã mang sẵn _pdx, cùng các liên kết mailto, tel, javascript và liên kết neo đều được để nguyên. Khi tới nơi, createWebClient đọc _pdx trước khi danh tính được dựng, ghi id và phiên mang tới vào kho chia sẻ, rồi gỡ tham số bằng history.replaceState nên nó không xuất hiện trong $current_url và cũng không đi tiếp; một tham số mà ba phần không đọc được sẽ bị bỏ qua và địa chỉ giữ nguyên. Nếu host này đã giữ một id ẩn danh khác, client gửi $create_alias, nên những gì ghi trước đó gập vào id mang tới; còn host đã định danh một người thì giữ nguyên người ấy: id mang tới trở thành id ẩn danh của họ, không bao giờ là distinct id của họ.

import { createWebClient } from '@prodantix/sdk/web';

const prodantix = createWebClient({
  apiKey: PRODANTIX_PUBLIC_KEY,
  host: 'https://eu.api.prodantix.com',
  linkedDomains: ['example.com', 'example-app.com'],
});

// A link to example-app.com now leaves as
// https://example-app.com/pricing?_pdx=<anonymousId>~<sessionId>~<startedAt>
// and the arriving page adopts it before it builds an identity of its own.

// The visitor's answer, from your own consent banner.
prodantix.setConsent({ identityLink: false });
prodantix.consent(); // { identityLink: false }

Câu trả lời của chính khách truy cập về việc gộp đó đi cùng kho chia sẻ ấy, dưới khóa pdx..consent, nên mọi tên miền phụ và một máy chủ đọc cookie đều thấy một câu trả lời. Hãy ghi lại bằng setConsent({ identityLink: false }), đọc lại bằng consent(), và gieo sẵn bằng tùy chọn consent khi ứng dụng của bạn đã giữ câu trả lời: biểu ngữ đồng ý là của bạn để dựng, còn prodantix tôn trọng những gì nó thu được. Khi identityLink là false, identify không gửi id ẩn danh nào để gộp vào người đó, và liên kết tới một tên miền đã liệt kê cũng không được trang trí, vì mang id sang chính là cũng việc gộp ấy bằng con đường khác. Chưa đặt hoặc true thì cho phép cả hai, nhưng vẫn theo thiết lập riêng của dự án trong console, do state worker thi hành chứ không phải bất cứ thứ gì trình duyệt gửi lên. Đổi câu trả lời sẽ có hiệu lực ở lần identify kế tiếp và cú nhấp kế tiếp; những gì đã gộp thì không bị tách ra.

@prodantix/sdk/node

Vẫn client đó nhưng với mặc định phía máy chủ. Sự kiện được đệm lại và gửi đi ở nền, nên hãy gọi shutdown trước khi tiến trình thoát, nếu không lô cuối cùng sẽ không bao giờ rời đi.

import { createNodeClient } from '@prodantix/sdk/node';

// A node client streams flag changes over Socket.IO by default and refetches
// the snapshot on push; streamFlags: false leaves only the 30s poll.
const prodantix = createNodeClient({
  apiKey: process.env.PRODANTIX_PUBLIC_KEY,
  host: 'https://eu.api.prodantix.com',
  streamFlags: true,
});

prodantix.capture('job.completed', { properties: { queue: 'emails' } });
await prodantix.shutdown();

Một lần đăng nhập kết thúc bằng chuyển hướng phía máy chủ không vẽ trang nào, nên identify của chính trình duyệt không bao giờ chạy ở đó. readSharedIdentity(cookieHeader, apiKey) đọc cookie mà web client đã ghi và trả về id ẩn danh, phiên mà nó đang ở trong, cùng sự đồng ý của khách, hoặc null khi cookie vắng mặt hoặc không phải của SDK này. Sau đó link(distinctId, anonymousId, traits) gửi đúng một $identify mà trình duyệt lẽ ra đã gửi, cho hai id được đưa vào, và không đụng tới danh tính của chính client này. Trang đăng nhập của Bomdisoft gọi cả hai khi đăng nhập hoàn tất, bên trong một hàm duy nhất mà cả tám điểm đăng nhập của nó vốn đã gọi: đó là nơi subject của người dùng lần đầu được biết ở phía máy chủ trong khi cookie vẫn còn trên yêu cầu. Sáu trong số các điểm đó là server action không có đối tượng yêu cầu, nên hàm này nhận một chuỗi tiêu đề cookie thay vì một yêu cầu. Hãy bỏ qua link khi câu trả lời đọc về là identityLink false.

import { createNodeClient, readSharedIdentity } from '@prodantix/sdk/node';

const prodantix = createNodeClient({
  apiKey: PRODANTIX_PUBLIC_KEY,
  host: 'https://eu.api.prodantix.com',
});

// At sign-in completion, where the person is known and the browser's
// cookie is still on the request.
export const completeSignIn = (sub: string, cookieHeader: string): void => {
  const shared = readSharedIdentity(cookieHeader, PRODANTIX_PUBLIC_KEY);
  if (shared !== null && shared.consent?.identityLink !== false) {
    prodantix.link(sub, shared.anonymousId);
  }
};

@prodantix/sdk/csp

Các nguồn của chính sách bảo mật nội dung mà một ứng dụng cần để tới được Prodantix. Nó không nhập gì từ React hay trình duyệt, nên tệp cấu hình bản dựng có thể đọc trực tiếp.

import { prodantixConnectSrc, prodantixImgSrc, prodantixScriptSrc } from '@prodantix/sdk/csp';

const hosts = {
  ingest: 'https://eu.api.prodantix.com',
  edge: 'https://eu.edge.prodantix.com',
  replay: 'https://eu.replay.prodantix.com',
};

const policy = [
  `connect-src ${prodantixConnectSrc(hosts)}`,
  `script-src ${prodantixScriptSrc(hosts)}`,
  `img-src ${prodantixImgSrc(hosts, ["'self'", 'data:'])}`,
].join('; ');

Tiện ích hỗ trợ hiển thị ảnh của đội bạn từ edge và vẽ các tệp khách truy cập gửi từ địa chỉ blob:, nên img-src của chính sách cần cả hai. prodantixImgSrc thêm chúng vào các nguồn ảnh bạn đã cho phép. Thiếu chúng, trình duyệt sẽ chặn những ảnh đó và chỉ báo trong bảng điều khiển của chính nó.

@prodantix/sdk/chat

Tiện ích hỗ trợ. Gắn nó vào và bạn nhận một handle để mở, đóng, huỷ và định danh người dùng. Nó dựng bên trong một shadow root đóng, nên kiểu dáng của trang chủ nhà không bao giờ chạm tới.

import { mountChat } from '@prodantix/sdk/chat';

const messenger = mountChat({
  apiKey: PRODANTIX_PUBLIC_KEY,
  host: 'https://eu.edge.prodantix.com',
  distinctId: prodantix.distinctId,
});

document.querySelector('#help')?.addEventListener('click', () => messenger.open());

Mỗi tin nhắn của khách đều mang theo nơi nó được viết. Bảng đọc location và document.title ngay lúc gửi rồi đăng host, path và title, trong đó path chỉ là tên đường dẫn: không bao giờ là chuỗi truy vấn và không bao giờ là mảnh neo, vì một liên kết đặt lại, một liên kết ma thuật hay một lần quay về từ thanh toán đều mang mã của nó ở đó, và hộp thư của nhân viên không phải chỗ cho thứ ấy. Bảng không vẽ bất cứ phần nào trong đó, nên luồng của khách vẫn chỉ là lời của chính họ, và câu trả lời từ edge về SDK cũng bỏ nó đi, nên một trang đang đọc luồng của chính mình không thể thấy điều console thấy. Nơi nó hiện ra là hộp thư đến, dưới dạng một dòng mờ bên dưới lượt tin nhắn đến.

@prodantix/sdk/messenger

Bộ đọc cấu hình phía sau tiện ích: nó lấy cấu hình trình nhắn tin của một dự án, lưu đệm, và cho biết dự án đã bật trình nhắn tin hay chưa. Đoạn mã tự chạy được dựng riêng và không thể lấy qua đường dẫn con này.

import { fetchMessengerConfig } from '@prodantix/sdk/messenger';

const config = await fetchMessengerConfig({
  apiKey: PRODANTIX_PUBLIC_KEY,
  host: 'https://eu.edge.prodantix.com',
});

if (config?.enabled) {
  // the project has the messenger switched on
}