الانتقال إلى المحتوى الرئيسي
مثالي لتطبيقات SaaS، والدردشة الذكية، وأدوات إنشاء المحتوى، وأي تطبيق مدعوم بـ LLM يحتاج إلى فوترة قائمة على الاستخدام.

بدء سريع

ابدأ مع تتبع رموز LLM التلقائي في دقيقتين فقط:
1

تثبيت SDK

قم بتثبيت مخططات إدخال مدفوعات Dodo:
npm install @dodopayments/ingestion-blueprints
2

احصل على مفاتيح API الخاصة بك

ستحتاج إلى مفتاحي API:
قم بتخزين مفاتيح API الخاصة بك بشكل آمن في متغيرات البيئة. لا تقم أبداً بإدخالها في التحكم في الإصدارات.
3

إنشاء عداد في مدفوعات Dodo

قبل تتبع الاستخدام، قم بإنشاء عداد في لوحة معلومات مدفوعات Dodo الخاصة بك:
  1. تسجيل الدخول إلى لوحة معلومات مدفوعات Dodo
  2. انتقل إلى المنتجات → العدادات
  3. انقر على “إنشاء عداد”
  4. قم بتكوين عدادك:
    • اسم العداد: اختر اسمًا وصفيًا (مثل “استخدام رموز LLM”)
    • اسم الحدث: قم بتعيين معرف حدث فريد (مثل llm.chat_completion)
    • نوع التجميع: اختر sum لجمع عدد الرموز
    • على خاصية: اختر ما يجب تتبعه:
      • inputTokens - تتبع رموز الإدخال/الطلب
      • outputTokens - تتبع رموز الإخراج/الاكتمال (تشمل رموز التفكير عند الاقتضاء)
      • totalTokens - تتبع الرموز المجمعة للإدخال + الإخراج
يجب أن يتطابق اسم الحدث الذي تحدده هنا تمامًا مع ما تمرره إلى SDK (حساس لحالة الأحرف).
للحصول على تعليمات مفصلة، راجع دليل الفوترة القائمة على الاستخدام.
4

تتبع استخدام الرموز

قم بلف عميل LLM الخاص بك وابدأ في التتبع تلقائيًا:
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import { generateText } from 'ai';
import { google } from '@ai-sdk/google';

const llmTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'aisdk.usage',
});

const client = llmTracker.wrap({
  client: { generateText },
  customerId: 'customer_123'
});

const response = await client.generateText({
  model: google('gemini-2.0-flash'),
  prompt: 'Hello!',
  maxOutputTokens: 500
});

console.log('Usage:', response.usage);
هذا كل شيء! كل استدعاء API الآن يتتبع تلقائيًا استخدام الرموز ويرسل الأحداث إلى مدفوعات Dodo للفوترة.

التكوين

تكوين المتتبع

قم بإنشاء متتبع مرة واحدة عند بدء التطبيق مع هذه المعلمات المطلوبة:
apiKey
string
required
مفتاح API الخاص بك لمدفوعات Dodo. احصل عليه من صفحة مفاتيح API.
apiKey: process.env.DODO_PAYMENTS_API_KEY
environment
string
required
وضع البيئة للمتتبع.
  • test_mode - استخدمه للتطوير والاختبار
  • live_mode - استخدمه للإنتاج
environment: 'test_mode' // or 'live_mode'
استخدم دائمًا test_mode أثناء التطوير لتجنب التأثير على مقاييس الإنتاج.
eventName
string
required
اسم الحدث الذي يحفز عدادك. يجب أن يتطابق تمامًا مع ما قمت بتكوينه في عداد مدفوعات Dodo الخاص بك (حساس لحالة الأحرف).
eventName: 'llm.chat_completion'
يربط اسم الحدث هذا استخدامك المتتبع بالعداد الصحيح لحساب الفوترة.

تكوين الغلاف

عند لف عميل LLM الخاص بك، قدم هذه المعلمات:
client
object
required
مثيل عميل LLM الخاص بك (OpenAI و Anthropic و Groq، إلخ).
client: openai
customerId
string
required
معرف العميل الفريد للفوترة. يجب أن يتطابق مع معرف العميل الخاص بك في مدفوعات Dodo.
customerId: 'customer_123'
استخدم معرف المستخدم أو معرف العميل الخاص بتطبيقك لضمان دقة الفوترة لكل عميل.
metadata
object
بيانات إضافية اختيارية لإرفاقها بحدث التتبع. مفيدة للتصفية والتحليل.
metadata: {
  feature: 'chat',
  userTier: 'premium',
  sessionId: 'session_123',
  modelVersion: 'gpt-4'
}

مثال كامل على التكوين

import { createLLMTracker } from "@dodopayments/ingestion-blueprints";
import { generateText } from "ai";
import { google } from "@ai-sdk/google";
import "dotenv/config";

async function aiSdkExample() {
  console.log("🤖 AI SDK Simple Usage Example\n");

  try {
    // 1. Create tracker
    const llmTracker = createLLMTracker({
      apiKey: process.env.DODO_PAYMENTS_API_KEY!,
      environment: "test_mode",
      eventName: "your_meter_event_name",
    });

    // 2. Wrap the ai-sdk methods
    const client = llmTracker.wrap({
      client: { generateText },
      customerId: "customer_123",
      metadata: {
        provider: "ai-sdk",
      },
    });

    // 3. Use the wrapped function
    const response = await client.generateText({
      model: google("gemini-2.5-flash"),
      prompt: "Hello, I am a cool guy! Tell me a fun fact.",
      maxOutputTokens: 500,
    });

    console.log(response);
    console.log(response.usage);
    console.log("✅ Automatically tracked for customer\n");
  } catch (error) {
    console.error(error);
  }
}

aiSdkExample().catch(console.error);
التتبع التلقائي: يقوم SDK بتتبع استخدام الرموز تلقائيًا في الخلفية دون تعديل الاستجابة. يظل كودك نظيفًا ومطابقًا لاستخدام SDKs المزود الأصلي.

المزودون المدعومون

يعمل مخطط LLM بسلاسة مع جميع مزودي LLM الرئيسيين والمجمعين:
تتبع الاستخدام مع Vercel AI SDK لدعم LLM الشامل.
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import { generateText } from 'ai';
import { google } from '@ai-sdk/google';

const llmTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'aisdk.usage',
});

const client = llmTracker.wrap({
  client: { generateText },
  customerId: 'customer_123',
  metadata: {
    model: 'gemini-2.0-flash',
    feature: 'chat'
  }
});

const response = await client.generateText({
  model: google('gemini-2.0-flash'),
  prompt: 'Explain neural networks',
  maxOutputTokens: 500
});

console.log('Usage:', response.usage);
المقاييس المتعقبة:
  • inputTokensinputTokens
  • outputTokens + reasoningTokensoutputTokens
  • totalTokenstotalTokens
  • اسم النموذج
عند استخدام نماذج قادرة على التفكير من خلال AI SDK (مثل Google Gemini 2.5 Flash مع وضع التفكير)، يتم تضمين رموز التفكير تلقائيًا في عدد outputTokens للفوترة الدقيقة.
تتبع استخدام الرموز عبر أكثر من 200 نموذج عبر واجهة OpenRouter الموحدة.
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import OpenAI from 'openai';

// OpenRouter uses OpenAI-compatible API
const openrouter = new OpenAI({
  baseURL: 'https://openrouter.ai/api/v1',
  apiKey: process.env.OPENROUTER_API_KEY
});

const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'openrouter.usage'
});

const client = tracker.wrap({ 
  client: openrouter, 
  customerId: 'user_123',
  metadata: { provider: 'openrouter' }
});

const response = await client.chat.completions.create({
  model: 'qwen/qwen3-max',
  messages: [{ role: 'user', content: 'What is machine learning?' }],
  max_tokens: 500
});

console.log('Response:', response.choices[0].message.content);
console.log('Usage:', response.usage);
المقاييس المتعقبة:
  • prompt_tokensinputTokens
  • completion_tokensoutputTokens
  • total_tokenstotalTokens
  • اسم النموذج
يوفر OpenRouter الوصول إلى نماذج من OpenAI و Anthropic و Google و Meta والعديد من المزودين الآخرين من خلال واجهة برمجة تطبيقات واحدة.
تتبع استخدام الرموز من نماذج GPT الخاصة بـ OpenAI تلقائيًا.
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import OpenAI from 'openai';

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'openai.usage'
});

const client = tracker.wrap({ 
  client: openai, 
  customerId: 'user_123' 
});

// All OpenAI methods work automatically
const response = await client.chat.completions.create({
  model: 'gpt-4',
  messages: [{ role: 'user', content: 'Explain quantum computing' }]
});

console.log('Total tokens:', response.usage.total_tokens);
المقاييس المتعقبة:
  • prompt_tokensinputTokens
  • completion_tokensoutputTokens
  • total_tokenstotalTokens
  • اسم النموذج
تتبع استخدام الرموز من نماذج Claude الخاصة بـ Anthropic.
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });

const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'anthropic.usage'
});

const client = tracker.wrap({ 
  client: anthropic, 
  customerId: 'user_123' 
});

const response = await client.messages.create({
  model: 'claude-sonnet-4-0',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'Explain machine learning' }]
});

console.log('Input tokens:', response.usage.input_tokens);
console.log('Output tokens:', response.usage.output_tokens);
المقاييس المتعقبة:
  • input_tokensinputTokens
  • output_tokensoutputTokens
  • totalTokens محسوبة
  • اسم النموذج
تتبع استدلال LLM فائق السرعة مع Groq.
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import Groq from 'groq-sdk';

const groq = new Groq({ apiKey: process.env.GROQ_API_KEY });

const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'groq.usage'
});

const client = tracker.wrap({ 
  client: groq, 
  customerId: 'user_123' 
});

const response = await client.chat.completions.create({
  model: 'llama-3.1-8b-instant',
  messages: [{ role: 'user', content: 'What is AI?' }]
});

console.log('Tokens:', response.usage);
المقاييس المتعقبة:
  • prompt_tokensinputTokens
  • completion_tokensoutputTokens
  • total_tokenstotalTokens
  • اسم النموذج
تتبع استخدام الرموز من نماذج Gemini الخاصة بـ Google عبر Google GenAI SDK.
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import { GoogleGenAI } from '@google/genai';

const googleGenai = new GoogleGenAI({ 
  apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY 
});

const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
  eventName: 'gemini.usage'
});

const client = tracker.wrap({ 
  client: googleGenai, 
  customerId: 'user_123' 
});

const response = await client.models.generateContent({
  model: 'gemini-2.5-flash',
  contents: 'Explain quantum computing'
});

console.log('Response:', response.text);
console.log('Usage:', response.usageMetadata);
المقاييس المتعقبة:
  • promptTokenCountinputTokens
  • candidatesTokenCount + thoughtsTokenCountoutputTokens
  • totalTokenCounttotalTokens
  • إصدار النموذج
وضع التفكير في Gemini: عند استخدام نماذج Gemini مع قدرات التفكير/التفكير (مثل Gemini 2.5 Pro)، يقوم SDK تلقائيًا بتضمين thoughtsTokenCount (رموز التفكير) في outputTokens لتعكس بدقة التكلفة الحسابية الكاملة.

الاستخدام المتقدم

مزودون متعددون

تتبع الاستخدام عبر مزودي LLM مختلفين مع متتبعين منفصلين:
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import OpenAI from 'openai';
import Groq from 'groq-sdk';
import Anthropic from '@anthropic-ai/sdk';
import { GoogleGenAI } from '@google/genai';

// Create separate trackers for different providers
const openaiTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'openai.usage'
});

const groqTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'groq.usage'
});

const anthropicTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'anthropic.usage'
});

const geminiTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'gemini.usage'
});

const openrouterTracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'live_mode',
  eventName: 'openrouter.usage'
});

// Initialize clients
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });
const groq = new Groq({ apiKey: process.env.GROQ_API_KEY });
const anthropic = new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY });
const googleGenai = new GoogleGenAI({ apiKey: process.env.GOOGLE_GENERATIVE_AI_API_KEY });
const openrouter = new OpenAI({ 
  baseURL: 'https://openrouter.ai/api/v1',
  apiKey: process.env.OPENROUTER_API_KEY 
});

// Wrap clients
const trackedOpenAI = openaiTracker.wrap({ client: openai, customerId: 'user_123' });
const trackedGroq = groqTracker.wrap({ client: groq, customerId: 'user_123' });
const trackedAnthropic = anthropicTracker.wrap({ client: anthropic, customerId: 'user_123' });
const trackedGemini = geminiTracker.wrap({ client: googleGenai, customerId: 'user_123' });
const trackedOpenRouter = openrouterTracker.wrap({ client: openrouter, customerId: 'user_123' });

// Use whichever provider you need
const response = await trackedOpenAI.chat.completions.create({...});
// or
const geminiResponse = await trackedGemini.models.generateContent({...});
// or
const openrouterResponse = await trackedOpenRouter.chat.completions.create({...});
استخدم أسماء أحداث مختلفة لمزودين مختلفين لتتبع الاستخدام بشكل منفصل في العدادات الخاصة بك.

تكامل API مع Express.js

مثال كامل على دمج تتبع LLM في API Express.js:
import express from 'express';
import { createLLMTracker } from '@dodopayments/ingestion-blueprints';
import OpenAI from 'openai';

const app = express();
app.use(express.json());

// Initialize OpenAI client
const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

// Create tracker once at startup
const tracker = createLLMTracker({
  apiKey: process.env.DODO_PAYMENTS_API_KEY,
  environment: process.env.NODE_ENV === 'production' ? 'live_mode' : 'test_mode',
  eventName: 'api.chat_completion'
});

// Chat endpoint with automatic tracking
app.post('/api/chat', async (req, res) => {
  try {
    const { message, userId } = req.body;
    
    // Validate input
    if (!message || !userId) {
      return res.status(400).json({ error: 'Missing message or userId' });
    }
    
    // Wrap client for this specific user
    const trackedClient = tracker.wrap({
      client: openai,
      customerId: userId,
      metadata: { 
        endpoint: '/api/chat',
        timestamp: new Date().toISOString()
      }
    });
    
    // Make LLM request - automatically tracked
    const response = await trackedClient.chat.completions.create({
      model: 'gpt-4',
      messages: [{ role: 'user', content: message }],
      temperature: 0.7
    });
    
    const completion = response.choices[0].message.content;
    
    res.json({ 
      message: completion,
      usage: response.usage
    });
  } catch (error) {
    console.error('Chat error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

app.listen(3000, () => {
  console.log('Server running on port 3000');
});

ما الذي يتم تتبعه

كل استدعاء API لـ LLM يرسل تلقائيًا حدث استخدام إلى مدفوعات Dodo بالهيكل التالي:
{
  "event_id": "llm_1673123456_abc123",
  "customer_id": "customer_123",
  "event_name": "llm.chat_completion",
  "timestamp": "2024-01-08T10:30:00Z",
  "metadata": {
    "inputTokens": 10,
    "outputTokens": 25,
    "totalTokens": 35,
    "model": "gpt-4",
  }
}

حقول الحدث

event_id
string
معرف فريد لهذا الحدث المحدد. يتم إنشاؤه تلقائيًا بواسطة SDK.التنسيق: llm_[timestamp]_[random]
customer_id
string
معرف العميل الذي قدمته عند لف العميل. يستخدم للفوترة.
event_name
string
اسم الحدث الذي يحفز عدادك. يتطابق مع تكوين المتتبع الخاص بك.
timestamp
string
تاريخ ووقت ISO 8601 عندما حدث الحدث.
metadata
object
استخدام الرموز وبيانات تتبع إضافية:
  • inputTokens - عدد رموز الإدخال/الطلب المستخدمة
  • outputTokens - عدد رموز الإخراج/الاكتمال المستخدمة (تشمل رموز التفكير عند الاقتضاء)
  • totalTokens - إجمالي الرموز (الإدخال + الإخراج)
  • model - نموذج LLM المستخدم (مثل “gpt-4”)
  • provider - مزود LLM (إذا تم تضمينه في بيانات الغلاف)
  • أي بيانات تعريف إضافية قدمتها عند لف العميل
رموز التفكير: بالنسبة للنماذج ذات قدرات التفكير، يتضمن outputTokens تلقائيًا كل من رموز الاكتمال ورموز التفكير.
يستخدم عداد مدفوعات Dodo الخاص بك حقول metadata (خاصة inputTokens، outputTokens أو totalTokens) لحساب الاستخدام والفوترة.