diff --git a/api_docs/changelog.md b/api_docs/changelog.md index 5bdc4ac60d..fd6bed63a1 100644 --- a/api_docs/changelog.md +++ b/api_docs/changelog.md @@ -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** diff --git a/zerver/openapi/zulip.yaml b/zerver/openapi/zulip.yaml index f5738a25cf..deacc30377 100644 --- a/zerver/openapi/zulip.yaml +++ b/zerver/openapi/zulip.yaml @@ -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: