# Truy xuất dữ liệu phễu

> Truy xuất dữ liệu phễu để theo dõi hành trình của người dùng qua các giai đoạn cụ thể trong quy trình chuyển đổi.
>
> 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/funnel/
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/funnel/:
    post:
      summary: Truy xuất dữ liệu phễu
      description: |-
        Truy xuất dữ liệu phễu để theo dõi hành trình của người dùng qua các giai đoạn cụ thể trong quy trình chuyển đổi.

        Giới hạn tốc độ: 2 yêu cầu mỗi giây.
      operationId: retrieveFunnelData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/FunnelDataRequest"
            examples:
              basic:
                summary: Yêu cầu dữ liệu phễu cơ bản
                value:
                  filters:
                    date:
                      - "2024-01-01"
                      - "2024-12-31"
                    compare_date:
                      - "2023-01-01"
                      - "2023-12-31"
                    offer_category:
                      - promotional
                  period_unit: quarter
                  show_value_as: absolute
                  format: csv
      responses:
        "200":
          description: Đã truy xuất dữ liệu phễu thành công
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/FunnelDataResponse"
              example:
                data:
                  - title: Total
                    type: total
                    values:
                      - period: -2
                        title: Install
                        value: 2
                        value_relative: 100
                        relative_changes: 0
                        following_changes:
                          title: Drop off
                          value: 2
                          value_relative: 100
                        churn_reason_title: ""
                        churn_reasons: []
                        values: []
                      - period: -1
                        title: Paywall displayed
                        value: 0
                        value_relative: 0
                        relative_changes: 0
                        following_changes:
                          title: Drop off
                          value: 0
                          value_relative: 0
                        churn_reason_title: ""
                        churn_reasons: []
                        values: []
            text/csv:
              schema:
                type: string
                description: Dữ liệu phễu ở đị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:
    FunnelDataRequest:
      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
        show_value_as:
          type: string
          enum:
            - absolute
            - relative
            - both
          description: Chỉ định cách hiển thị giá trị
        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
    FunnelDataResponse:
      type: object
      description: Phản hồi chứa dữ liệu phân tích phễu hiển thị hành trình của người dùng qua các giai đoạn chuyển đổi
      properties:
        data:
          type: array
          description: Mảng các phân khúc phễu hiển thị các giai đoạn khác nhau của quá trình chuyển đổi
          items:
            $ref: "#/components/schemas/FunnelSegment"
    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
    FunnelSegment:
      type: object
      description: Một phân khúc phễu đại diện cho một giai đoạn trong quá trình chuyển đổi
      properties:
        title:
          type: string
          description: Tiêu đề hiển thị của phân khúc phễu này
        type:
          type: string
          description: Loại phân khúc phễu ('total' cho dữ liệu tổng hợp)
        values:
          type: array
          description: Mảng các giá trị phễu hiển thị hành trình qua các giai đoạn
          items:
            $ref: "#/components/schemas/FunnelValue"
    FunnelValue:
      type: object
      description: Giá trị giai đoạn phễu riêng lẻ hiển thị hành trình và tỷ lệ rời bỏ của người dùng
      properties:
        period:
          type: integer
          description: Số kỳ trong phễu (-2 = Cài đặt, -1 = Hiển thị paywall, v.v.)
        title:
          type: string
          description: Tiêu đề hiển thị của giai đoạn phễu này
        value:
          type: integer
          description: Số người dùng đạt đến giai đoạn này
        value_relative:
          type: number
          description: Tỷ lệ phần trăm người dùng đạt đến giai đoạn này so với giai đoạn đầu tiên
        relative_changes:
          type: number
          description: Thay đổi tỷ lệ chuyển đổi so với kỳ trước
        following_changes:
          type: object
          description: Thông tin về người dùng đã rời bỏ sau giai đoạn này
          properties:
            title:
              type: string
              description: Tiêu đề cho giai đoạn rời bỏ
            value:
              type: integer
              description: Số người dùng đã rời bỏ
            value_relative:
              type: number
              description: Tỷ lệ phần trăm người dùng đã rời bỏ
        churn_reason_title:
          type: string
          description: Tiêu đề mô tả lý do rời bỏ ở giai đoạn này
        churn_reasons:
          type: array
          description: Mảng các lý do rời bỏ cụ thể
          items:
            type: object
        values:
          type: array
          description: Các giá trị lồng nhau bổ sung cho giai đoạn phễu này
          items:
            type: object
  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_...`.
```