# Truy xuất dữ liệu giữ chân người dùng

> Truy xuất dữ liệu giữ chân người dùng để phân tích khả năng của sản phẩm trong việc duy trì sự tương tác của người dùng theo thời gian.
>
> 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/retention/
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/retention/:
    post:
      summary: Truy xuất dữ liệu giữ chân người dùng
      description: |-
        Truy xuất dữ liệu giữ chân người dùng để phân tích khả năng của sản phẩm trong việc duy trì sự tương tác của người dùng theo thời gian.

        Giới hạn tốc độ: 2 yêu cầu mỗi giây.
      operationId: retrieveRetentionData
      security:
        - apikeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RetentionDataRequest"
            examples:
              basic:
                summary: Yêu cầu dữ liệu giữ chân người dùng cơ bản
                value:
                  filters:
                    date:
                      - "2024-01-01"
                      - "2024-12-31"
                    compare_date:
                      - "2023-01-01"
                      - "2023-12-31"
                  period_unit: quarter
                  period_type: renewals
                  segmentation: store_product_id
                  format: csv
      responses:
        "200":
          description: Đã truy xuất dữ liệu giữ chân người dùng thành công
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RetentionDataResponse"
              example:
                data: []
                title: Subscription retention
                metric_name: Subscription retention
                description: Absolute value is the amount of users who entered the current step - subscribed for a trial or paid for a subscription. Relative is calculated as a percentage of these users among those who got a trial. So it starts with 100% for the trial step.
                value_type: null
            text/csv:
              schema:
                type: string
                description: Dữ liệu giữ chân người dùng ở đị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:
    RetentionDataRequest:
      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
        segmentation:
          type: string
          description: Đặt cơ sở để phân khúc
        use_trial:
          type: boolean
          description: Giá trị boolean cho biết có sử dụng bản dùng thử hay không
          default: false
        format:
          type: string
          enum:
            - json
            - csv
          description: Chỉ định định dạng tệp xuất
          default: json
    RetentionDataResponse:
      type: object
      description: Phản hồi chứa dữ liệu giữ chân người dùng hiển thị mức độ tương tác của người dùng theo thời gian
      properties:
        data:
          type: array
          description: Mảng các điểm dữ liệu giữ chân người dùng (có thể rỗng đối với một số loại giữ chân)
          items:
            type: object
        title:
          type: string
          description: Tiêu đề hiển thị của chỉ số giữ chân người dùng
        metric_name:
          type: string
          description: Tên nội bộ của chỉ số giữ chân người dùng
        description:
          type: string
          description: Giải thích cách tính giữ chân người dùng (giá trị tuyệt đối so với tương đối)
        value_type:
          type: string
          nullable: true
          description: Loại giá trị giữ chân người dùng (tuyệt đối hoặc tương đối)
    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
  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_...`.
```