# Truy xuất dữ liệu cohort

> Truy xuất dữ liệu cohort để theo dõi các nhóm người dùng theo thời gian.
>
> Doanh thu từ endpoint này dựa trên **cohort theo ngày cài đặt**: doanh thu của từng người dùng được quy cho **ngày cài đặt** của họ, không phải ngày giao dịch. Phản hồi cung cấp `total_revenue_usd` và `total_proceeds_usd`. Hãy sử dụng endpoint này (thay vì endpoint phân tích) để đối chiếu báo cáo nội bộ với Ads Manager, vốn cũng dựa trên cohort/ngày cài đặt.
>
> 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/cohort/
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/cohort/:
    post:
      summary: Truy xuất dữ liệu cohort
      description: |-
        Truy xuất dữ liệu cohort để theo dõi các nhóm người dùng theo thời gian.

        Doanh thu từ endpoint này dựa trên **cohort theo ngày cài đặt**: doanh thu của từng người dùng được quy cho **ngày cài đặt** của họ, không phải ngày giao dịch. Phản hồi cung cấp `total_revenue_usd` và `total_proceeds_usd`. Hãy sử dụng endpoint này (thay vì endpoint phân tích) để đối chiếu báo cáo nội bộ với Ads Manager, vốn cũng dựa trên cohort/ngày cài đặt.

        Giới hạn tốc độ: 2 yêu cầu mỗi giây.
      operationId: retrieveCohortData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CohortDataRequest"
            examples:
              basic:
                summary: Yêu cầu dữ liệu cohort cơ bản
                value:
                  filters:
                    date:
                      - "2024-04-01"
                      - "2024-09-30"
                    store:
                      - app_store
                    country:
                      - us
                  period_unit: month
                  period_type: renewals
                  value_type: absolute
                  value_field: subscriptions
      responses:
        "200":
          description: Đã truy xuất dữ liệu cohort thành công
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CohortDataResponse"
              example:
                data:
                  - segment_start_date: "2024-04-01"
                    type: total
                    title: Total
                    total_installs: 0
                    total_subscriptions: 0
                    total_paid_subscribers: 0
                    total_revenue_usd: 0
                    total_proceeds_usd: 0
                    total_net_revenue_usd: 0
                    total_anrpas_usd: 0
                    total_appas_usd: 0
                    total_arpas_usd: 0
                    total_anrppu_usd: 0
                    total_apppu_usd: 0
                    total_arppu_usd: 0
                    total_anrpu_usd: 0
                    total_appu_usd: 0
                    total_arpu_usd: 0
                    predict: null
                    values:
                      - arpas_usd: 0
                        appas_usd: 0
                        anrpas_usd: 0
                        anrppu_usd: 0
                        apppu_usd: 0
                        arppu_usd: 0
                        anrpu_usd: 0
                        appu_usd: 0
                        arpu_usd: 0
                        installs: 0
                        period: 1
                        revenue_usd: 0
                        proceeds_usd: 0
                        net_revenue_usd: 0
                        revenue_relative: 0
                        proceeds_relative: 0
                        net_revenue_relative: 0
                        subscriptions: 0
                        subscriptions_relative: 0
                        subscribers: 0
                        subscribers_relative: 0
                        currently_active_period: false
            text/csv:
              schema:
                type: string
                description: Dữ liệu cohort ở đị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:
    CohortDataRequest:
      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
          default: month
        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
          default: renewals
        value_type:
          type: string
          enum:
            - absolute
            - relative
          description: Chỉ định cách hiển thị giá trị
          default: absolute
        value_field:
          type: string
          enum:
            - revenue
            - arppu
            - arpu
            - arpas
            - subscribers
            - subscriptions
          description: Chỉ định loại giá trị được hiển thị
          default: revenue
        accounting_type:
          type: string
          enum:
            - revenue
            - proceeds
            - net_revenue
          description: Phương pháp kế toán được sử dụng
          default: revenue
        renewal_days:
          type: array
          items:
            type: integer
          description: Danh sách số ngày kể từ khi cài đặt ứng dụng cho loại cohort period_type=days
        prediction_months:
          type: integer
          enum:
            - 3
            - 6
            - 9
            - 12
            - 18
            - 24
          description: Nhập số tháng dự đoán bạn muốn
          default: 12
        format:
          type: string
          enum:
            - json
            - csv
          description: Chỉ định định dạng tệp xuất
          default: json
    CohortDataResponse:
      type: object
      description: Phản hồi chứa dữ liệu phân tích cohort hiển thị hành vi người dùng theo thời gian
      properties:
        data:
          type: array
          description: Mảng các phân khúc cohort, mỗi phân khúc đại diện cho một nhóm người dùng bắt đầu trong cùng một kỳ
          items:
            $ref: "#/components/schemas/CohortSegment"
    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
    CohortSegment:
      type: object
      description: Một phân khúc cohort đại diện cho những người dùng bắt đầu trong cùng một kỳ
      properties:
        segment_start_date:
          type: string
          description: Ngày bắt đầu của phân khúc cohort này
        type:
          type: string
          description: Loại phân khúc ('total' cho dữ liệu tổng hợp, 'single' cho cohort riêng lẻ)
        title:
          type: string
          description: Tiêu đề hiển thị của phân khúc cohort này
        total_installs:
          type: integer
          description: Tổng số lần cài đặt ứng dụng trong cohort này
        total_subscriptions:
          type: integer
          description: Tổng số gói đăng ký trong cohort này
        total_paid_subscribers:
          type: integer
          description: Tổng số người đăng ký trả phí trong cohort này
        total_revenue_usd:
          type: number
          description: Tổng doanh thu tính bằng USD của cohort này
        total_proceeds_usd:
          type: number
          description: Tổng số tiền nhận được tính bằng USD của cohort này (sau phí cửa hàng)
        total_net_revenue_usd:
          type: number
          description: Tổng doanh thu ròng tính bằng USD của cohort này
        total_anrpas_usd:
          type: number
          description: Tổng Doanh thu ròng trung bình trên mỗi người đăng ký đang hoạt động (ANRPAS) tính bằng USD
        total_appas_usd:
          type: number
          description: Tổng số tiền nhận được trung bình trên mỗi người đăng ký đang hoạt động (APPAS) tính bằng USD
        total_arpas_usd:
          type: number
          description: Tổng Doanh thu trung bình trên mỗi người đăng ký đang hoạt động (ARPAS) tính bằng USD
        total_anrppu_usd:
          type: number
          description: Tổng Doanh thu ròng trung bình trên mỗi người dùng trả phí (ANRPPU) tính bằng USD
        total_apppu_usd:
          type: number
          description: Tổng số tiền nhận được trung bình trên mỗi người dùng trả phí (APPPU) tính bằng USD
        total_arppu_usd:
          type: number
          description: Tổng Doanh thu trung bình trên mỗi người dùng trả phí (ARPPU) tính bằng USD
        total_anrpu_usd:
          type: number
          description: Tổng Doanh thu ròng trung bình trên mỗi người dùng (ANRPU) tính bằng USD
        total_appu_usd:
          type: number
          description: Tổng số tiền nhận được trung bình trên mỗi người dùng (APPU) tính bằng USD
        total_arpu_usd:
          type: number
          description: Tổng Doanh thu trung bình trên mỗi người dùng (ARPU) tính bằng USD
        predict:
          type: object
          nullable: true
          description: Dữ liệu dự đoán cho cohort này (nếu có)
        values:
          type: array
          description: Mảng các giá trị theo kỳ hiển thị hiệu suất cohort theo thời gian
          items:
            $ref: "#/components/schemas/CohortValue"
    CohortValue:
      type: object
      description: Giá trị kỳ riêng lẻ trong một phân khúc cohort hiển thị các chỉ số hiệu suất cho một khoảng thời gian cụ thể
      properties:
        arpas_usd:
          type: number
          description: Doanh thu trung bình trên mỗi người đăng ký đang hoạt động tính bằng USD cho kỳ này
        appas_usd:
          type: number
          description: Số tiền nhận được trung bình trên mỗi người đăng ký đang hoạt động tính bằng USD cho kỳ này
        anrpas_usd:
          type: number
          description: Doanh thu ròng trung bình trên mỗi người đăng ký đang hoạt động tính bằng USD cho kỳ này
        anrppu_usd:
          type: number
          description: Doanh thu ròng trung bình trên mỗi người dùng trả phí tính bằng USD cho kỳ này
        apppu_usd:
          type: number
          description: Số tiền nhận được trung bình trên mỗi người dùng trả phí tính bằng USD cho kỳ này
        arppu_usd:
          type: number
          description: Doanh thu trung bình trên mỗi người dùng trả phí tính bằng USD cho kỳ này
        anrpu_usd:
          type: number
          description: Doanh thu ròng trung bình trên mỗi người dùng tính bằng USD cho kỳ này
        appu_usd:
          type: number
          description: Số tiền nhận được trung bình trên mỗi người dùng tính bằng USD cho kỳ này
        arpu_usd:
          type: number
          description: Doanh thu trung bình trên mỗi người dùng tính bằng USD cho kỳ này
        installs:
          type: integer
          description: Số lần cài đặt ứng dụng trong kỳ này
        period:
          type: integer
          description: Số kỳ (1 = kỳ đầu tiên, 2 = kỳ thứ hai, v.v.)
        revenue_usd:
          type: number
          description: Tổng doanh thu tính bằng USD cho kỳ này
        proceeds_usd:
          type: number
          description: Tổng số tiền nhận được tính bằng USD cho kỳ này (sau phí cửa hàng)
        net_revenue_usd:
          type: number
          description: Tổng doanh thu ròng tính bằng USD cho kỳ này
        revenue_relative:
          type: number
          description: Doanh thu theo tỷ lệ phần trăm so với kỳ đầu tiên (100% = kỳ đầu tiên)
        proceeds_relative:
          type: number
          description: Số tiền nhận được theo tỷ lệ phần trăm so với kỳ đầu tiên (100% = kỳ đầu tiên)
        net_revenue_relative:
          type: number
          description: Doanh thu ròng theo tỷ lệ phần trăm so với kỳ đầu tiên (100% = kỳ đầu tiên)
        subscriptions:
          type: integer
          description: Số gói đăng ký trong kỳ này
        subscriptions_relative:
          type: number
          description: Gói đăng ký theo tỷ lệ phần trăm so với kỳ đầu tiên (100% = kỳ đầu tiên)
        subscribers:
          type: integer
          description: Số người đăng ký trong kỳ này
        subscribers_relative:
          type: number
          description: Người đăng ký theo tỷ lệ phần trăm so với kỳ đầu tiên (100% = kỳ đầu tiên)
        currently_active_period:
          type: boolean
          description: Đây có phải là kỳ đang hoạt động hiện tại của cohort hay không
  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_...`.
```