# Truy xuất dữ liệu Lifetime Value (LTV)

> Truy xuất dữ liệu LTV để đánh giá tiềm năng doanh thu dài hạn của khách hàng trong suốt thời gian tương tác.
>
> Giới hạn tốc độ: 2 yêu cầu mỗi giây.

## OpenAPI

```yaml
/api-specs/export-analytics-api.yaml post /api/v1/client-api/metrics/ltv/
openapi: 3.1.0
info:
  title: Adapty Export Analytics API
  version: 1.0.0
  description: |
    Adapty Export Analytics API cho phép bạn xuất dữ liệu phân tích sang định dạng CSV hoặc JSON,
    giúp bạn linh hoạt khám phá sâu hơn các chỉ số hiệu suất của ứng dụng, tùy chỉnh báo cáo
    và phân tích xu hướng theo thời gian. Với API này, bạn có thể dễ dàng truy xuất dữ liệu phân tích
    chi tiết, thuận tiện cho việc theo dõi, chia sẻ và tinh chỉnh thông tin dữ liệu khi cần.
servers:
  - url: https://api-admin.adapty.io
    description: Production server
security:
  - apikeyAuth: []
paths:
  /api/v1/client-api/metrics/ltv/:
    post:
      summary: Truy xuất dữ liệu Lifetime Value (LTV)
      description: |-
        Truy xuất dữ liệu LTV để đánh giá tiềm năng doanh thu dài hạn của khách hàng trong suốt thời gian tương tác.

        Giới hạn tốc độ: 2 yêu cầu mỗi giây.
      operationId: retrieveLTVData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/LTVDataRequest"
            examples:
              basic:
                summary: Yêu cầu dữ liệu LTV cơ bản
                value:
                  filters:
                    date:
                      - "2024-01-01"
                      - "2024-12-31"
                    compare_date:
                      - "2023-01-01"
                      - "2023-12-31"
                    offer_category:
                      - introductory
                    store:
                      - app_store
                    country:
                      - us
                    attribution_source:
                      - appsflyer
                    attribution_status:
                      - organic
                    attribution_channel:
                      - social_media
                  period_unit: quarter
                  period_type: renewals
                  segmentation: store_product_id
                  format: csv
      responses:
        "200":
          description: Đã truy xuất dữ liệu LTV thành công
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/LTVDataResponse"
              example:
                revenue:
                  data:
                    - title: Total
                      type: total
                      value: 0
                      values: []
                      cohort_size: 0
                  description: |-
                    <div>LTV (Lifetime Value) is calculated as revenue for the period / number of subscribers on start.
                     It's an actual, not predicted LTV.
                     <a target="_blank" rel="noopener noreferrer" href='https://adapty.io/docs/ltv'> Read more</a>.</div>
                  value: 0
                  unit: USD
                  title: LTV
                proceeds:
                  data:
                    - title: Total
                      type: total
                      value: 0
                      values: []
                      cohort_size: 0
                  description: |-
                    <div>LTV (Lifetime Value) is calculated as revenue for the period / number of subscribers on start.
                     It's an actual, not predicted LTV.
                     <a target="_blank" rel="noopener noreferrer" href='https://adapty.io/docs/ltv'> Read more</a>.</div>
                  value: 0
                  unit: USD
                  title: LTV
                net_revenue:
                  data:
                    - title: Total
                      type: total
                      value: 0
                      values: []
                      cohort_size: 0
                  description: |-
                    <div>LTV (Lifetime Value) is calculated as revenue for the period / number of subscribers on start.
                     It's an actual, not predicted LTV.
                     <a target="_blank" rel="noopener noreferrer" href='https://adapty.io/docs/ltv'> Read more</a>.</div>
                  value: 0
                  unit: USD
                  title: LTV
            text/csv:
              schema:
                type: string
                description: Dữ liệu LTV ở định dạng CSV
        "400":
          description: Yêu cầu không hợp lệ
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ErrorResponse"
        "401":
          description: Không được phép
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UnauthorizedError"
        "429":
          description: Đã vượt quá giới hạn tốc độ. Tối đa 2 yêu cầu mỗi giây cho mỗi API key.
components:
  schemas:
    LTVDataRequest:
      type: object
      required:
        - filters
      properties:
        filters:
          $ref: "#/components/schemas/MetricsFilters"
        period_unit:
          type: string
          enum:
            - day
            - week
            - month
            - quarter
            - year
          description: Chỉ định khoảng thời gian để tổng hợp dữ liệu phân tích
        period_type:
          type: string
          enum:
            - renewals
            - days
          description: Phân tích dữ liệu theo lần gia hạn hoặc theo ngày
        segmentation:
          type: string
          description: Đặt cơ sở để phân khúc
        format:
          type: string
          enum:
            - json
            - csv
          description: Chỉ định định dạng tệp xuất
          default: json
    LTVDataResponse:
      type: object
      description: Phản hồi chứa dữ liệu Lifetime Value (LTV) cho các loại doanh thu khác nhau
      properties:
        revenue:
          $ref: "#/components/schemas/LTVMetric"
          description: LTV được tính bằng doanh thu gộp
        proceeds:
          $ref: "#/components/schemas/LTVMetric"
          description: LTV được tính bằng số tiền nhận được (sau phí cửa hàng)
        net_revenue:
          $ref: "#/components/schemas/LTVMetric"
          description: LTV được tính bằng doanh thu ròng
    ErrorResponse:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              errors:
                type: array
                items:
                  type: string
        error_code:
          type: string
        status_code:
          type: integer
    UnauthorizedError:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              source:
                type: string
              errors:
                type: array
                items:
                  type: string
        error_code:
          type: string
        status_code:
          type: integer
    MetricsFilters:
      type: object
      required:
        - date
      properties:
        date:
          type: array
          items:
            type: string
          description: Nhập ngày hoặc khoảng thời gian bạn muốn truy xuất dữ liệu biểu đồ
        compare_date:
          type: array
          items:
            type: string
          description: Nhập ngày hoặc khoảng thời gian để so sánh
        store:
          type: array
          items:
            type: string
          description: Lọc theo cửa hàng ứng dụng nơi thực hiện giao dịch mua
        country:
          type: array
          items:
            type: string
          description: Lọc theo mã quốc gia 2 chữ cái nơi thực hiện giao dịch mua
        store_product_id:
          type: array
          items:
            type: string
          description: Mã định danh duy nhất của sản phẩm từ cửa hàng ứng dụng
        duration:
          type: array
          items:
            type: string
          description: Chỉ định thời hạn gói đăng ký
        attribution_source:
          type: array
          items:
            type: string
          description: Nguồn tích hợp cho attribution
        attribution_status:
          type: array
          items:
            type: string
          description: Cho biết attribution là organic hay non-organic
        attribution_channel:
          type: array
          items:
            type: string
          description: Kênh marketing dẫn đến giao dịch
        attribution_campaign:
          type: array
          items:
            type: string
          description: Chiến dịch marketing mang lại giao dịch
        attribution_adgroup:
          type: array
          items:
            type: string
          description: Nhóm quảng cáo attribution mang lại giao dịch
        attribution_adset:
          type: array
          items:
            type: string
          description: Bộ quảng cáo attribution dẫn đến giao dịch
        attribution_creative:
          type: array
          items:
            type: string
          description: Các yếu tố hình ảnh hoặc văn bản cụ thể trong quảng cáo hoặc chiến dịch được theo dõi để đo lường hiệu quả
        offer_category:
          type: array
          items:
            type: string
          description: Chỉ định các danh mục ưu đãi bạn muốn truy xuất dữ liệu
        offer_type:
          type: array
          items:
            type: string
          description: Chỉ định các loại ưu đãi bạn muốn truy xuất dữ liệu
        offer_id:
          type: array
          items:
            type: string
          description: Chỉ định các ưu đãi cụ thể bạn muốn truy xuất dữ liệu
    LTVMetric:
      type: object
      description: Chỉ số LTV riêng lẻ chứa dữ liệu cohort và các tính toán
      properties:
        data:
          type: array
          description: Mảng các điểm dữ liệu LTV cho các cohort khác nhau
          items:
            $ref: "#/components/schemas/LTVData"
        description:
          type: string
          description: Mô tả HTML giải thích cách tính LTV
        value:
          type: number
          description: Giá trị LTV tổng thể
        unit:
          type: string
          description: Đơn vị đo lường (thường là 'USD')
        title:
          type: string
          description: Tiêu đề hiển thị của chỉ số LTV này
    LTVData:
      type: object
      description: Điểm dữ liệu LTV riêng lẻ cho một cohort cụ thể
      properties:
        title:
          type: string
          description: Tiêu đề hiển thị của điểm dữ liệu LTV này
        type:
          type: string
          description: Loại dữ liệu LTV ('total' cho dữ liệu tổng hợp)
        value:
          type: number
          description: Giá trị LTV cho cohort này
        values:
          type: array
          description: Mảng các giá trị LTV theo kỳ
          items:
            type: object
        cohort_size:
          type: integer
          description: Số người dùng trong cohort này
  securitySchemes:
    apikeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: |
        Bạn cần xác thực các yêu cầu API bằng secret API key của mình trong header Authorization.
        Bạn có thể tìm thấy key này trong App Settings. Định dạng là `Api-Key {YOUR_SECRET_API_KEY}`,
        ví dụ: `Api-Key secret_live_...`.
```