Best Practices

Following these best practices will help you build a high-quality, compliant, and efficient integration with the VKRA API.

Privacy & Security

VKRA is designed to be privacy-first. Your integration should reflect this.

1. Never Send PII: Do not include Personally Identifiable Information (PII) like names, emails, or phone numbers in your search queries or conversation context.
2. Anonymous Session IDs: If using session_id, ensure it is an anonymous UUID that cannot be traced back to a specific user's identity outside of your system.
3. Secure API Keys: Treat your API keys as secrets. Use environment variables and never commit them to public repositories.

Performance Optimization

AI agents require low-latency responses. Here's how to keep your integration fast.

1. Parallel Execution: If your agent is performing multiple tasks, fetch recommendations in parallel with other I/O operations.
2. Timeouts: Set aggressive timeouts (e.g., 2000ms) on API calls. It's often better to show no products than to delay the entire agent response.
3. Caching: For common or generic queries, consider implement local caching to avoid redundant API calls.

User Experience

Contextual recommendations should enhance, not interrupt, the user flow.

1. Natural Language Explanations: Use the relevance_explanation field to help your agent explain why a product is being recommended.
2. Disclosure Text: Always display the required affiliate disclosure. This builds trust and ensures compliance.
3. Relevance Thresholds: Use min_relevance_score to filter out products that don't meet your quality bar. A high threshold (e.g., 0.7) ensures only highly relevant products are shown.
4. Loading States: If you are using a UI, use skeleton loaders or subtle indicators so the user knows recommendations are being fetched.

Attribution & Compliance

1. Track Every Click: Use the /clicks endpoint for every user interaction. This is required for your revenue tracking.
2. Fresh Data: Respect the last_updated_at field. If pricing or availability data is more than 24 hours old, consider re-fetching.
3. Correct Destination: Always use the url provided in the AdResponse as the final destination for the user click.

Error Handling

Implement robust error handling with graceful fallbacks.

try {
  const ads = await fetchAds(context);
  renderAds(ads);
} catch (error) {
  // Gracefully handle failure - the agent should still function
  console.error("VKRA not available", error);
  renderAlternativeContent(); 
}