openapi: 3.0.0
info:
  title: Screens
  description: The screens API provides analytics for screen/page navigation and user interface interactions within your application. These endpoints enables analysis of screen usage patterns, user flow tracking, and interface engagement metrics with flexible grouping capabilities.
  contact: {}
  version: 1.0.0
servers:
  - url: https://apptics.zoho.com/cx/api/v1
    description: API Endpoint
tags:
  - name: screens
    description: Screens Module
paths:
  /screen/multigroup:
    get:
      tags:
        - screens
      summary: Get screens count by group
      description: The get screens Count by group API provides flexible screen analytics with customizable grouping and aggregation capabilities. This endpoint allows you to analyze screen data across multiple dimensions simultaneously, creating hierarchical breakdowns of screen counts based on specified grouping criteria. The API requires a date range and grouping configuration, with optional filtering by platform and screen name. The unique grouping system enables multi-dimensional analysis by combining up to three grouping entities such as device type, platform, bundle, date, app version and country. The response structure dynamically adapts to match your grouping configuration, creating nested JSON hierarchies that reflect the specified group order. For example, grouping by "platform,country,devicetype" returns data organized first by platform, then by country within each platform, and finally by device type within each country. This flexible structure supports complex analytical queries and enables detailed segmentation analysis.
      parameters:
        - $ref: '#/components/parameters/zsoid'
        - $ref: '#/components/parameters/projectid'
        - $ref: '#/components/parameters/startdate'
        - $ref: '#/components/parameters/enddate'
        - $ref: '#/components/parameters/group'
        - $ref: '#/components/parameters/screename'
        - $ref: '#/components/parameters/platform'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/screens-count-by-group-response'
      security:
        - Zoho_Auth:
            - JProxy.jmobileapi.ALL
  /screen/retention:
    get:
      tags:
        - screens
      summary: Get device retention count by screens
      description: The get device retention count by screens API measures user retention based on screen interactions within your application. This endpoint analyzes how many devices continue to engage with specific screens over different time periods, providing insights into user retention patterns and screen effectiveness in maintaining user interest. The API requires date range, platform, granularity, and timezone parameters, with optional filtering by application bundle and environment mode. It calculates retention metrics by tracking devices that interact with specified screens during the initial period and return in subsequent periods. The unique screen filtering system allows inclusion or exclusion of specific screens from retention calculations, enabling focused analysis on particular user flows or features.
      parameters:
        - $ref: '#/components/parameters/zsoid'
        - $ref: '#/components/parameters/projectid'
        - $ref: '#/components/parameters/startdate'
        - $ref: '#/components/parameters/enddate'
        - name: platform
          description: Platform to filter screens (iOS, Android, Windows, tvOS, watchOS, macOS). Default - all platforms.
          in: query
          required: true
          schema:
            type: string
          example: Android
        - name: granularity
          description: 'Time interval for retention calculation. Values: "day" (daily retention), "week" (weekly retention), "month" (monthly retention).'
          in: query
          required: true
          schema:
            type: string
          example: week
        - $ref: '#/components/parameters/bundle'
        - $ref: '#/components/parameters/mode'
        - $ref: '#/components/parameters/timezone'
        - name: include
          description: 'Comma-separated list of screens to include in retention calculation. Default: all screens in the specified platform. Maximum 25 screens.'
          in: query
          schema:
            type: string
          example: Dashboard,LoginPage
        - name: exclude
          description: 'Comma-separated list of screens to exclude from retention calculation. Default: no exclusions. Maximum 25 screens.'
          in: query
          schema:
            type: string
          example: SettingsPage,ErrorPage
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/screens-retention-response'
      security:
        - Zoho_Auth:
            - JProxy.jmobileapi.ALL
components:
  parameters:
    zsoid:
      name: zsoid
      description: Portal ID
      in: header
      required: true
      schema:
        type: string
      example: '10234695'
    projectid:
      name: projectid
      description: Project ID
      in: header
      required: true
      schema:
        type: string
      example: '12345689'
    startdate:
      name: startdate
      description: Beginning of date range for data retrieval, required format - dd-MM-yyyy
      in: query
      required: true
      schema:
        type: string
      example: 02-08-2025
    enddate:
      name: enddate
      description: End of date range for data retrieval, required format - dd-MM-yyy
      in: query
      required: true
      schema:
        type: string
      example: 24-08-2025
    platform:
      name: platform
      description: Platform to filter Screens (iOS, Android, Windows, tvOS, watchOS, macOS). Default - all platforms.
      in: query
      required: false
      schema:
        type: string
      example: Android
    group:
      name: group
      description: Comma-separated list of grouping entities (devicetype, platform, bundle, date, appversion, country, event). Maximum 3 groups. Response structure follows the specified group order in nested JSON format.
      in: query
      required: true
      schema:
        type: string
      example: platform,devicetype
    appversion:
      name: appversion
      description: Comma-separated list of app versions to filter Screens. Default - all app versions. Maximum 10 values allowed.
      in: query
      required: false
      schema:
        type: string
      example: 1.0,1.1,1.2
    mode:
      name: mode
      description: Environment filter. 0 for development, 1 for production. Default - 1 (production).
      in: query
      required: false
      schema:
        type: string
      example: 0
    offset:
      name: offset
      description: Starting position for result pagination (default - 0). Increment by limit value for next page (e.g., 501, 1001).
      in: query
      required: false
      schema:
        type: string
      example: 501
    limit:
      name: limit
      description: 'Number of results per page. Default and maximum: 500. Use smaller values to limit response size.'
      in: query
      required: false
      schema:
        type: string
      example: 100
    screename:
      name: screenname
      description: A specific Screen to filter.
      in: query
      required: false
      schema:
        type: string
      example: Dashboard
    bundle:
      name: bundle
      description: Application Id/ Bundle Id to filter
      in: query
      required: false
      schema:
        type: string
      example: com.example.demo
    timezone:
      name: timezone
      description: Timezone for data aggregation.(e.g., "America/New_York", "Asia/Tokyo")
      in: query
      required: true
      schema:
        type: string
      example: Asia/Kolkata
  schemas:
    screens-retention-response:
      type: object
      properties:
        result:
          type: object
          properties:
            week-27:
              type: object
              properties:
                week-27:
                  type: integer
                  example: 1027
                week-28:
                  type: integer
                  example: 990
            week-28:
              type: object
              properties:
                week-28:
                  type: integer
                  example: 1100
        status:
          type: integer
          example: 200
    screens-count-by-group-response:
      type: object
      properties:
        result:
          type: object
          properties:
            iOS:
              type: object
              properties:
                iPhone:
                  type: integer
                  example: 155248
                iPad:
                  type: integer
                  example: 3496
            Android:
              type: object
              properties:
                Phone:
                  type: integer
                  example: 40011
                Tablet:
                  type: integer
                  example: 1110
                Foldables:
                  type: integer
                  example: 1186
        status:
          type: string
          example: success
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      flows:
        implicit:
          authorizationUrl: https://accounts.zoho.com/oauth/v2/auth
          scopes:
            JProxy.jmobileapi.ALL: Analytics & Insight view
