Add Static Location and Live Location Support

[nuno-vieira]

🔗 Issue Links

Resolves https://linear.app/stream/issue/IOS-578/location-attachment

🎯 Goal

Adds support for static and live location attachments in the Low-Level Client SDK.

The UI has been implemented in the Demo App to demonstrate how to use the new location APIs.

📝 Summary

New APIs:

• ChatChannelController
  • sendStaticLocation() - Sends a static location message to the channel.
  • startLiveLocationSharing() - Starts a live location-sharing message in the channel.
  • stopLiveLocationSharing() - Stops sharing the live location message in the channel.
• ChatMessageController
  • updateMessage() - Updates the message partially. (It was missing from the SDK)
  • updateLiveLocation() - Updates the message's live location attachment if it has one.
  • stopLiveLocationSharing() - Stops sharing the live location attachment if it has one.
• CurrentChatUserController
  • updateLiveLocation() - Updates the location of all active live location messages for the current user. Internally, it uses the Message Controller to update each message that has a live location attachment.
• CurrentChatUserControllerDelegate
  • didStartSharingLiveLocation() - Notifies whenever the current user is sharing a live location.
  • didStopSharingLiveLocation() - Notifies whenever the current user stops sharing a live location.
  • didChangeActiveLiveLocationMessages() - Notifies whenever the live location messages update.
• Throttler
  • The Throttler was part of the UI SDK somehow, so it was moved to the LLC and made public like the Debouncer.
• ChatMessage
  • staticLocationAttachments - Returns the attachments of .staticLocation type.
  • liveLocationAttachments - Returns the attachments of .liveLocation type.
• AttachmentType
  • .staticLocation
  • .liveLocation
• ChatMessageLiveLocationAttachment & LiveLocationAttachmentPayload
• ChatMessageStaticLocationAttachment & StaticLocationAttachmentPayload

Out of Scope

• End Time: The backend does not support this out of the box yet, and there's no contract yet for this. But we should add this as soon as possible since all of the common apps have this feature.
• Multi-Device: At the moment, there is no protection against the user sharing the location between multiple devices. The location will be shared from both devices since, at the moment, we don't have a way to attach the device ID or the device model to an attachment. Since this is an edge case, it can be left for future improvement.

🛠 Implementation

The SDK at the moment only handles updating the location attachments. The location tracking should be provided by the App. Something like the LocationProvider in the Demo App should be implemented by the customer.

Creating a location attachment

In order to create a new message with a location attachment, the developer can use the ChannelController.sendStaticLocation() or the ChannelController.startSharingLiveLocation(). If more fine control is needed, it is also possible to add the attachments by using the ChannelController.createNewMessage() and pass the location attachment payload as an argument.

Sending location updates (Live Location)

The customer is responsible for sending new location updates to the SDK. This is done through the CurrentChatUserController.updateLiveLocation() method. This method will update all the current user's active location attachments. Internally, it uses a activeLiveLocationMessagesObserver that keeps track of the active location attachments of the current user. These changes are also available to the customer through the CurrentChatUserControllerDelegate to make it easier for the developer to know when it should track location updates and when it can turn them off.

Stopping live location attachment

To stop a live location attachment, it can be done through 2 methods:

• ChatChannelController.stopLiveLocationSharing(): This one will automatically get the current active location attachment in that channel and stop it.
• ChatMessageController.stopLiveLocationSharing(): Directly tries to stop a live location attachment in the given message if it has an active location attachment. This is especially useful in Message Actions, where having the ChannelController is not possible or difficult.

Overall Data Flow

sequenceDiagram
    participant App
    participant LocationProvider
    participant SDK
    participant Backend

    Note over App,Backend: Start New Location Share
    App->>LocationProvider: getCurrentLocation()
    LocationProvider-->>App: Return current location
    App->>SDK: startLiveLocationSharing(location)
    SDK->>Backend: Create location message
    Backend-->>SDK: Confirm creation
    SDK->>App: onStartLiveLocationSharing()
    App->>LocationProvider: startMonitoring()

    Note over App,Backend: Location Updates
    LocationProvider->>LocationProvider: Monitor location changes
    LocationProvider->>SDK: didUpdateLocation(location)
    SDK->>Backend: updateLiveLocation
    Note over SDK: 3s Throttling

    Note over App,Backend: Stop Location Share
    App->>SDK: stopLiveLocationSharing()
    SDK->>Backend: Stop location sharing
    Backend-->>SDK: Confirm stop
    SDK->>App: onStopLiveLocationSharing()
    App->>LocationProvider: stopMonitoring()

Loading

🎨 Showcase

Static	Live
static.mp4	live.mp4

🧪 Manual Testing Notes

Note: To simulate live location updates in the Simulator, with the Simulator selected, Go to Features > Location > City Bicycle Ride in the top bar of the Mac.

Static

1. Open the Demo App
2. Tap on Configuration
3. Enable Location Attachments (Skip this step if Stream Developers scheme is being used)
4. Open a Channel
5. Tap on Attachments Icon
6. Tap "Send Current Location"
7. It should render an image of the map with a Pin
8. Tapping the attachment should open the map with the Pin

Live

1. Open the Demo App
2. Tap on Configuration
3. Enable Location Attachments (Skip this step if Stream Developers scheme is being used)
4. Open a Channel
5. Tap on Attachments Icon
6. Tap "Share Live Location"
7. It should render an image of the map with the avatar of the user
   • The image is static and does not update. It is generated when the channel is opened.
   • The avatar does not have the blue pulse animation. This is due to the fact that we reload the cell on every update, which would restart the animation.
8. Tapping the attachment should open the map with the user's avatar, and it should follow his location.
9. Tapping the "Stop Sharing" button should stop sharing the live location.

Make sure to test from the current user's perspective and the other user's perspective.

☑️ Contributor Checklist

• I have signed the Stream CLA (required)
• This change should be manually QAed
• Changelog is updated with client-facing changes
• Changelog is updated with new localization keys
• New code is covered by unit tests
• Comparison screenshots added for visual changes
• Affected documentation updated (docusaurus, tutorial, CMS)

[martinmitrevski]

Couldn't test a lot, since a had constant crashes (shared details on Slack). Let's figure that out first, then I will do another round.

[github-actions]

	1 Warning
⚠️	Big PR

Generated by 🚫 Danger

[Stream-SDK-Bot]

SDK Size

title	develop	branch	diff	status
StreamChat	6.98 MB	7.07 MB	+93 KB	🟢
StreamChatUI	4.77 MB	4.77 MB	-1 KB	🚀

[martinmitrevski]

Looks good! Left few comments, let me know what you think.

[martinmitrevski]

LGTM! ✅

[sonarqubecloud]

Quality Gate passed

Issues
190 New issues
0 Accepted issues

Measures
0 Security Hotspots
83.4% Coverage on New Code
0.4% Duplication on New Code

See analysis details on SonarQube Cloud