Mirror
/
zulip
mirror of https://github.com/zulip/zulip.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

api-docs: Clean up feature level 233 and 230 documentation. 

Updates the API changelog entries and changes notes for feature
levels 233 and 230, which both are related to the onboarding
steps (hotspots and one-time notices) updates.

Feature level 233 was originally documented in commit 83bd9955e3
and ac8af3d6de.

Feature level 230 was originally documented in commit 8d633cc36.
This commit is contained in:
Lauryn Menard 2024-01-05 17:07:50 +01:00 committed by Tim Abbott
parent 02e98f7fa2
commit c0be6c6b98
2 changed files with 62 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
api_docs/changelog.md
View File

@ -172,20 +172,22 @@ No changes; feature level used for Zulip 8.0 release.
**Feature level 233**
* [`POST /register`](/api/register-queue), [`GET /events`](/api/get-events):
Renamed the event type `hotspots` and the `hotspots` array field in it
to `onboarding_steps` as this event is sent to clients with remaining
onboarding steps data that includes hotspots and one-time notices to display.
Earlier, we had hotspots only. Added a `type` field to the objects in
the renamed `onboarding_steps` array to distinguish between the two type
of onboarding steps.
Renamed the `hotspots` event type and the related `hotspots` object array
to `onboarding_steps`. These are sent to clients if there are onboarding
steps to display to the user. Onboarding steps now include
both hotspots and one-time notices. Prior to this, hotspots were the only
type of onboarding step. Also, added a `type` field to the objects
returned in the renamed `onboarding_steps` array to distinguish between
the two types of onboarding steps.
* `POST /users/me/onboarding_steps`: Added a new endpoint that
deprecates the `/users/me/hotspots` endpoint. Added support for
displaying one-time notices in addition to existing hotspots.
This is now used as a common endpoint to mark both types of
onboarding steps, i.e., 'hotspot' and 'one_time_notice'.
There is no compatibility support for `/users/me/hotspots` as
no client other than web app has this feature currently.
* `POST /users/me/onboarding_steps`: Added a new endpoint, which
deprecates the `/users/me/hotspots` endpoint, in order to support
displaying both one-time notices (which highlight new features for
existing users) and hotspots (which are used in new user tutorials).
This endpoint marks both types of onboarding steps, i.e. `hotspot`
and `one_time_notice`, as read by the user. There is no compatibility
support for `/users/me/hotspots` as no client other than the Zulip
web app used the endpoint prior to these changes.
**Feature level 232**
@ -219,9 +221,10 @@ No changes; feature level used for Zulip 8.0 release.
**Feature level 230**
* [`GET /events`](/api/get-events): Added `has_trigger` field in
hotspots events to identify if a hotspot will activate only when
some specific event occurs.
* [`POST /register`](/api/register-queue), [`GET /events`](/api/get-events):
Added `has_trigger` field to objects returned in the `hotspots` array to
identify if the hotspot will activate only when some specific event
occurs.
**Feature level 229**

68
zerver/openapi/zulip.yaml
View File

@ -2291,14 +2291,15 @@ paths:
- type: object
additionalProperties: false
description: |
Event sent when the set of onboarding steps to show for
the current user have changed (E.g. because the user dismissed one).
Event sent when the set of onboarding steps to show for the current user
has changed (e.g. because the user dismissed one).
Clients that feature a similar tutorial experience to the Zulip
web app may want to handle these events.
Clients that feature a similar tutorial experience to the Zulip web app
may want to handle these events.
**Changes**: Before Zulip 8.0 (feature level 233), this was named
as `Hotspots`. One-time notice wasn't available earlier.
**Changes**: Before Zulip 8.0 (feature level 233), this event was named
`hotspots`. Prior to this feature level, one-time notice onboarding
steps were not supported.
properties:
id:
$ref: "#/components/schemas/EventIdSchema"
@ -2310,11 +2311,13 @@ paths:
onboarding_steps:
type: array
description: |
An array of dictionaries where each
dictionary contains details about a single onboarding step.
An array of dictionaries where each dictionary contains details about a
single onboarding step.
**Changes**: Before Zulip 8.0 (feature level 233), this array
was named as `hotspots`. One-time notice wasn't available earlier.
**Changes**: Before Zulip 8.0 (feature level 233), this array was named
`hotspots`. Prior to this feature level, one-time notice onboarding
steps were not supported, and the `type` field in these objects did not
exist as all onboarding steps were implicitly hotspots.
items:
$ref: "#/components/schemas/OnboardingStep"
example:
@ -2324,12 +2327,16 @@ paths:
[
{
"type": "hotspot",
"name": "intro_streams",
"title": "Catch up on a stream",
"description": "Messages sent to a stream are seen by everyone subscribed to that stream. Try clicking on one of the stream links below.",
"name": "intro_compose",
"title": "Compose",
"description": "Click here to start a new conversation. Pick a topic (2-3 words is best), and give it a go!",
"delay": 0.5,
"has_trigger": false,
},
{
"type": "one_time_notice",
"name": "visibility_policy_banner",
},
],
"id": 0,
}
@ -12610,9 +12617,14 @@ paths:
Present if `onboarding_steps` is present in `fetch_event_types`.
An array of dictionaries, where each dictionary contains details about
a single onboarding step that should be shown to new users.
a single onboarding step that should be shown to the user.
We expect that only official Zulip clients will interact with these data.
We expect that only official Zulip clients will interact with this data.
**Changes**: Before Zulip 8.0 (feature level 233), this array was named
`hotspots`. Prior to this feature level, one-time notice onboarding
steps were not supported, and the `type` field in these objects did not
exist as all onboarding steps were implicitly hotspots.
items:
$ref: "#/components/schemas/OnboardingStep"
max_message_id:
@ -19574,39 +19586,45 @@ components:
additionalProperties: false
description: |
Dictionary containing details of a single onboarding step.
**Changes**: Before Zulip 8.0 (feature level 233), this was
named as `Hotspot`. One-time notice wasn't available earlier.
properties:
type:
type: string
description: |
The type of the onboarding step. Valid values are either
'hotspot' or 'one_time_notice'.
`"hotspot"` or `"one_time_notice"`.
**Changes**: New in Zulip 8.0 (feature level 233).
name:
type: string
description: |
The name of the hotspot.
The name of the onboarding step.
title:
type: string
description: |
The title of the hotspot, as will be displayed to the user.
The title of the onboarding step, as displayed to the user.
Only present for onboarding steps with type `"hotspot"`.
description:
type: string
description: |
The description of the hotspot, as will be displayed to the
The description of the onboarding step, as displayed to the
user.
Only present for onboarding steps with type `"hotspot"`.
delay:
type: number
description: |
The delay after which the user should be shown the hotspot.
The delay, in seconds, after which the user should be shown
the onboarding step.
Only present for onboarding steps with type `"hotspot"`.
has_trigger:
type: boolean
description: |
The has_trigger is used to identify if the hotspot will activate
only when some specific event occurs.
Identifies if the onboarding step will activate only when some
specific event occurs.
Only present for onboarding steps with type `"hotspot"`.
**Changes**: New in Zulip 8.0 (feature level 230).
RealmAuthenticationMethod: