LogoLogo
SentianceInsights-Control-TowerLegacy DocsImportant Security Notice
  • Introduction
  • Integrating the SDK
    • Getting Started
    • Android Quick Start
      • 1. Including the SDK
      • 2. Initialization
      • 3. User Creation
      • 4. Enabling Detections
      • 5. SDK Status Updates
      • 6. Permissions
      • 7. Additional Requirements
    • iOS Quick Start
      • 1. Including the SDK
        • Using CocoaPods
        • Using Carthage
        • Using Swift Package Manager
        • Manual Integration
      • 2. Project Settings
      • 3. Initialization
      • 4. User Creation
      • 5. Enabling Detections
      • 6. SDK Status Updates
      • 7. Permissions
      • 8. Additional Requirements
    • React Native Quick Start
      • 1. Including the SDK
      • 2. Configuration
      • 3. Initialization
      • 4. User Creation
      • 5. Enabling Detections
      • 6. SDK Status Updates
    • Flutter Quick Start
      • 1. Including the SDK
      • 2. Configuration
      • 3. Initialization
      • 4. User Creation
      • 5. Enabling Detections
      • 6. SDK Status Updates
    • What Comes After Integration
    • Integration (FAQ)
    • Detections (FAQ)
  • Sentiance Insights
    • Overview of Sentiance Insights
      • Driving Insights
        • Transports
        • Driving Events and Scores
        • Car Crashes
      • Mobility and Lifestyle Insights
        • Visit Essentials
        • User Segmentation
    • Engagement
      • User Adaptive Score
      • Streaks
      • Challenges
      • Reward System
      • Communication Campaign
      • Social Groups
        • Technical Details
    • Accessing Sentiance Insights
      • via On Device API
      • via Cloud API
      • via Firehose - Realtime Messages
      • via Offloads
  • FAQ
    • Security, Privacy and Terms of Service (FAQ)
  • Important topics
    • SDK
      • Appendix
        • Android
          • Android 10 Update Behavior
          • Android Battery Optimization
          • Artifacts & Dependencies
          • Manifest Permissions
          • Notification Management
          • Sample Notification
          • Supported API Levels
        • iOS
          • App Store Privacy Section
          • App Store Release
          • Apple Privacy Manifest
          • ARM Simulator Support
          • Dependencies
          • iOS 13 permission changes
          • Supported iOS Versions & Architectures
          • Swift Support
          • v5.x Framework Files
          • v6.x Framework Files
        • Controlled Detections
          • Automatic Detections
          • Automatic Detections with Forced Trips
          • Controlled Trips Only
          • Checking Trip Status
        • Control Sending Data
        • Custom User Metadata
        • Detecting Vehicle Crashes
        • Feature Production Readiness
        • Migration Guide
          • Android
          • iOS
          • React Native
          • Flutter
        • On-Device Features
        • React Native
        • SDK Initialization
        • User Access Token
        • User Creation
        • User Linking
        • Xamarin
      • API Reference
        • Android
          • AsyncInitializationError
          • AsyncInitializationResult
          • DateTime
          • DetectionStatus
          • DisableDetectionsError
          • DisableDetectionsResult
          • Driving Insights
            • CallWhileMovingEvent
            • DrivingInsight
            • DrivingInsightsApi
            • DrivingInsightsReadyListener
            • HarshDrivingEvent
              • Type
            • PhoneUsageEvent
            • SafetyScores
            • SafetyScoreRequestParameters
              • Builder
              • OccupantRoles
              • Period
              • TransportModes
            • SpeedingEvent
          • Smart Geofences
            • DetectionMode
            • SmartGeofence
            • SmartGeofenceApi
            • SmartGeofenceEvent
              • Type
            • SmartGeofenceEventListener
            • SmartGeofencesRefreshError
              • SmartGeofencesRefreshFailureReason
            • SmartGeofencesRefreshResult
          • EnableDetectionsError
            • EnableDetectionsFailureReason
          • EnableDetectionsResult
          • EventTimeline
            • EventType
            • TransportMode
            • Event
              • OffTheGridEvent
              • StationaryEvent
              • TransportEvent
              • UnknownEvent
            • EventTimelineUpdateListener
            • EventTimelineApi
            • OccupantRole
            • Venue
              • VenueType
              • VenueSignificance
          • Feedback
            • FeedbackApi
            • OccupantRoleFeedback
            • OccupantRoleFeedbackResult
          • GeoLocation
          • InitializationResult
            • InitializationFailureReason
          • InitState
          • MetaUserLinker
          • MetaUserLinkerAsync
          • MetaUserLinkerCallback
          • OnInitCallback
            • InitIssue
          • OnSdkStatusUpdateHandler
          • OnStartFinishedHandler
          • PendingOperation
            • OnSuccessListener
            • OnFailureListener
            • OnFailureListener
            • OnCompleteListener
          • ResetCallback
            • ResetCallback.ResetFailureReason
          • ResetError
            • ResetFailureReason
          • ResetResult
          • SdkConfig
            • LocationPermission
            • Builder
          • SdkException
          • SdkStatus
            • LocationSetting
            • Quota Status
            • StartStatus
          • SdkStatusUpdateListener
          • Sentiance
          • SentianceOptions
            • SentianceOptions.Builder
          • StartTripError
            • StartTripFailureReason
          • StartTripResult
          • StationaryInfo
          • StopTripError
            • StopTripFailureReason
          • StopTripResult
          • SubmitDetectionsCallback
          • SubmitDetectionsError
            • SubmitDetectionsFailureReason
          • SubmitDetectionsResult
          • Token
          • TokenResultCallback
          • TransmittableDataType
          • Transport Sessions
            • SensorDataChunk
            • TransportSession
            • TransportSessionApi
            • TransportSessionListener
          • Trip
            • StartTripCallback
            • StopTripCallback
            • TransportMode
            • TripTimeoutListener
            • TripType
          • TripInfo
          • UserAccessTokenError
            • UserAccessTokenFailureReason
          • UserActivity
          • UserActivityListener
          • UserActivityType
          • UserContext
            • Attribute
            • Segment
              • SegmentCategory
              • SegmentSubcategory
              • SegmentType
            • SemanticTime
          • UserContextApi
            • RequestUserContextFailureReason
            • RequestUserContextError
            • UserContextUpdateCriteria
            • UserContextUpdateListener
          • UserCreationError
            • UserCreationFailureReason
          • UserCreationOptions
            • UserCreationOptions.Builder
          • UserCreationResult
            • UserInfo
          • UserLinker
          • UserLinkerAsync
          • UserLinkerCallback
          • UserLinkingError
            • UserLinkingFailureReason
          • UserLinkingResult
          • VehicleCrashDetection
            • CrashDetectionApi
            • CrashDetectionState
            • VehicleCrashDiagnostic
            • VehicleCrashEvent
            • VehicleCrashDiagnosticListener
            • VehicleCrashListener
            • VehicleCrashSeverity
          • Waypoint
        • iOS
          • Detections
            • Enable Detections
            • Disable Detections
          • Driving Insights
            • SENTCallWhileMovingEvent
            • SENTDrivingInsights
            • SENTDrivingInsightsReadyDelegate
            • SENTHarshDrivingEvent
              • HarshDrivingEventType
            • SENTPhoneUsageEvent
            • SENTSpeedingEvent
            • SENTSafetyScores
            • SafetyScoreRequestParameters
              • SafetyScoreRequestOccupantRoleOption
              • SafetyScoreRequestPeriod
              • SafetyScoreRequestTransportModeOption
          • Event Timeline
            • EventTimelineDelegate
            • SENTOccupantRole
            • SENTTimelineEvent
              • SENTOffTheGridEvent
              • SENTStationaryEvent
              • SENTTransportEvent
              • SENTUnknownEvent
            • SENTTimelineEventType
            • SENTTimelineTransportMode
            • SENTVenue
            • SENTVenueSignificance
            • SENTVenueType
          • Feedback
            • SENTFeedback
            • SENTOccupantRoleFeedback
            • SENTOccupantRoleFeedbackResult
          • SENTCompletionHandlers
          • SENTConfig
          • SENTDate
          • SENTGeolocation
          • SENTAsyncInitializationCompletionHandler
          • SENTAsyncInitializationError
          • SENTAsyncInitializationResult
          • Sentiance
          • SENTInitializationResult
          • SENTOptions
            • SENTOptionsInitPurpose
          • SENTPublicDefinitions
          • SENTSDKStatus
          • SENTToken
          • SENTTransmittableDataType
          • SENTUserActivity
          • SENTVehicleCrashDetectionState
          • SENTVehicleCrashDiagnostic
          • SENTVehicleCrashEvent
            • SENTVehicleCrashSeverity
          • SENTWaypoint
          • Smart Geofences
            • SENTSmartGeofencesRefreshHandler
            • SmartGeofenceDetectionMode
            • SmartGeofencesRefreshError
              • SmartGeofencesRefreshFailureReason
            • SmartGeofencesRefreshResult
            • SmartGeofence
            • SmartGeofenceEvent
              • SmartGeofenceEventType
            • SmartGeofenceEventDelegate
          • Transport Sessions
            • SENTAccelerometerDataIterator
            • SENTLocationDataIterator
            • SENTSensorDataChunk
            • SENTTransportSession
          • User Context
            • SENTAttribute
            • SENTRequestUserContextCompletionHandler
            • SENTRequestUserContextError
            • SENTRequestUserContextFailureReason
            • SENTSegment
              • SENTSegmentCategory
              • SENTSegmentSubCategory
              • SENTSegmentType
            • SENTSemanticTime
            • SENTUserContext
            • SENTUserContextDelegate
            • SENTUserContextUpdateCriteria
          • User Creation & Linking
            • SENTUserInfo
            • User Creation
              • SENTUserCreationResult
              • SENTUserCreationFailureReason
              • SENTUserCreationError
              • SENTUserCreationCompletionHandler
              • SENTUserCreationOptions
            • User Linking
              • SENTNoOpUserLinker
              • SENTUserLinkingResult
              • SENTUserLinkingFailureReason
              • SENTUserLinkingError
              • SENTUserLinkingCompletionHandler
              • SENTUserLinker
        • React Native
          • core
            • Definitions
            • Examples
          • crash-detection
            • Definitions
            • Examples
          • driving-insights
            • Definitions
            • Examples
          • smart-geofences
            • Definitions
            • Examples
          • event-timeline
            • Definitions
            • Examples
          • legacy
            • Definitions
            • Examples
          • user-context
            • Definitions
            • Examples
        • Flutter
      • Battery Optimization on Android
      • How To
        • Check the Location Permissions
        • Utilize the Event Timeline API
        • Utilize the Driving Insights API
        • Utilize the User Context API
        • Utilize the Smart Geofences API
      • Troubleshooting
        • Android
        • iOS
      • Changelog
        • Android
        • iOS
        • React Native
        • Flutter
    • Authentication and Authorization
    • User Creation (via Authentication Code)
    • User Deletion
    • PlayStore Location Access Review
    • Privacy Report & Dashboard
    • Crash Detection
    • Important Security Notice
    • Injecting Fake Data
    • Custom Aggregation For Analytics
    • Merging Scores for Motorcycles and Cars
  • Links
    • SDK Standard License
    • Insights-by-Sentiance Application
    • Insights-by-Sentiance Privacy Policy
    • Journeys License
    • Technical & Organizational Measures
Powered by GitBook
On this page
  • Group Management
  • Technical Implementation
  • Create Group Mutation
  • Remove Group Membership Mutation
  • Update Group Mutation
  • Delete Group Mutation
  • Approve Group Join Mutation
  • Decline Group Join Mutation
  • Make Group Admin Mutation
  • Unmake Group Admin Mutation
  • Join Group Mutation
  • Leave Group Mutation
  • Set In-Group Status Mutation
  • Create Group POI Mutation
  • Delete Group POI Mutation
  • Subscribe Group POI Mutation
  • Unsubscribe Group POI Mutation
  • Group Members Query
  • Group Leaderboard Query
  • Group Feed Query
  • Group POIs Query
  1. Sentiance Insights
  2. Engagement
  3. Social Groups

Technical Details

This section provides technical details to help you integrate the Social Groups feature into your application, including examples of GraphQL queries and mutations.

Group Management

Manage social groups effectively within your application using intuitive group management features.

Invitation-Based Groups

  • Registration Codes: Groups are invitation-based, utilising unique registration codes that can be shared.

  • Sharing Invitations: Users share the registration code with family and friends to invite them to join a group.

  • Secure Access: Only those with the registration code can request to join, keeping groups secure.

Membership Requests and Roles

  • Membership Approval: Existing group members can accept or decline membership requests from new users.

  • User Roles: Each member within a group is assigned a specific role:

    • ADMIN: Has full control over group settings, including managing members and approving requests.

    • MEMBER: Standard participant with access to all group features.

    • PENDING: Users who have requested to join the group and are awaiting approval.

  • Role Management: ADMINs can change the roles of members as needed to maintain group integrity.

Managing Groups

  • Approving Requests: Members receive notifications of pending requests and can approve or deny them.

  • Maintaining Privacy: The role system ensures that only approved members have access to the group's information and features.

Technical Implementation

Group Features

Groups have specific features selected during creation, which determine their behavior in subsequent mutations and queries. These features, such as live location tracking, leaderboard rankings, or Points of Interest (POIs), influence how the group’s data is managed and retrieved.

Available features:

  • leaderboard: set flag with_leaderboard to true

  • event feed: set flag with_feed to true

  • live locations: set flag with_locations to true

  • points of interest: set flag with_poi to true

Create Group Mutation

Description: Creates a new social group with specified attributes.

mutation Create_group(
  $features: CreateUserEngagementGroupRequest_UserEngagementGroupFeaturesInput, # Group features
  $name: String, # Name of the group
  $group_type: UserEngagementGroupTypeEnum, # Type of the group (e.g., SOCIAL)
  $origin: String, # Origin of the group (e.g., 'client_app')
  $ranking_attributes: [UserEngagementGroupRankingAttributeEnum] # Attributes for group ranking
) {
  create_group(
    features: $features,
    name: $name,
    group_type: $group_type,
    origin: $origin,
    ranking_attributes: $ranking_attributes
  ) {
    group {
      group_id # ID of the created group
      name # Name of the created group
      created_at # Timestamp of creation
      reg_code # Registration code to be used by other users to request memebership
    }
    status # Success or failure status
  }
}

# VARIABLES
{
  "features": { "with_locations": true },
  "name": "My Social Group",
  "group_type": "SOCIAL",
  "origin": "client_app",
  "ranking_attributes": ["DRIVER_COACHING_SCORE"]
}

Remove Group Membership Mutation

Description: Removes a user from a specified group.

mutation Remove_group_membership(
  $removed_user_id: String, # ID of the user to remove
  $group_id: String # ID of the group
) {
  remove_group_membership(
    removed_user_id: $removed_user_id,
    group_id: $group_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "removed_user_id": "abc123",
  "group_id": "xyz789"
}

Update Group Mutation

Description: Updates details of an existing group.

mutation Update_group(
  $group_id: String, # ID of the group to update
  $name: String # New name of the group
) {
  update_group(
    group_id: $group_id,
    name: $name
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "abc123",
  "name": "Updated Group Name"
}

Delete Group Mutation

Description: Deletes a group using its ID.

mutation Delete_group($group_id: String) { # ID of the group to delete
  delete_group(group_id: $group_id) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "abc123"
}

Approve Group Join Mutation

Description: Approves a pending request for a user to join a group.

mutation Approve_group_join(
  $pending_user_id: String, # ID of the pending user
  $group_id: String # ID of the group
) {
  approve_group_join(
    pending_user_id: $pending_user_id,
    group_id: $group_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "pending_user_id": "user123",
  "group_id": "group456"
}

Decline Group Join Mutation

Description: Declines a pending request for a user to join a group.

mutation Decline_group_join(
  $group_id: String, # ID of the group
  $pending_user_id: String # ID of the pending user
) {
  decline_group_join(
    group_id: $group_id,
    pending_user_id: $pending_user_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "group123",
  "pending_user_id": "user456"
}

Make Group Admin Mutation

Description: Assigns a user as an admin of a group.

mutation Make_group_admin(
  $group_id: String, # ID of the group
  $new_admin_user_id: String # ID of the new admin user
) {
  make_group_admin(
    group_id: $group_id,
    new_admin_user_id: $new_admin_user_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "group123",
  "new_admin_user_id": "user456"
}

Unmake Group Admin Mutation

Description: Removes a user's admin privileges in a group.

mutation Unmake_group_admin(
  $group_id: String, # ID of the group
  $removed_admin_user_id: String # ID of the admin to remove
) {
  unmake_group_admin(
    group_id: $group_id,
    removed_admin_user_id: $removed_admin_user_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "group123",
  "removed_admin_user_id": "user456"
}

Join Group Mutation

Description: Allows a user to join a group using a registration code.

mutation Join_group($reg_code: String) { # Registration code of the group
  join_group(reg_code: $reg_code) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "reg_code": "reg789"
}

Leave Group Mutation

Description: Allows a user to leave a group.

mutation Leave_group($group_id: String) { # ID of the group
  leave_group(group_id: $group_id) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "group456"
}

Set In-Group Status Mutation

Description: Sets a specific status for a user within a group.

mutation Set_in_group_status(
  $status: String, # Status of the user in the group
  $expire_in: Int, # Expiration time in seconds
  $group_id: String # ID of the group
) {
  set_in_group_status(
    status: $status,
    expire_in: $expire_in,
    group_id: $group_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "status": "Active",
  "expire_in": 31536000,  # 1 year
  "group_id": "group123"
}

Create Group POI Mutation

Description: Creates a new Point of Interest (POI) within a group.

mutation Create_group_poi(
  $group_id: String, # ID of the group
  $poi: EngagementPOIInput # POI details
) {
  create_group_poi(
    group_id: $group_id,
    poi: $poi
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "group123",
  "poi": {
    "name": "Central Park",
    "coordinates": {
      "latitude": 40.785091,
      "longitude": -73.968285
    },
    "radius": 100
  }
}

Delete Group POI Mutation

Description: Deletes a Point of Interest (POI) from a group.

mutation Delete_group_poi(
  $group_id: String, # ID of the group
  $poi_id: String # ID of the POI
) {
  delete_group_poi(
    group_id: $group_id,
    poi_id: $poi_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "group123",
  "poi_id": "poi456"
}

Subscribe Group POI Mutation

Description: Subscribes to updates related to a POI in a group.

mutation Subscribe_group_poi(
  $group_id: String, # ID of the group
  $poi_id: String # ID of the POI
) {
  subscribe_group_poi(
    group_id: $group_id,
    poi_id: $poi_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "group123",
  "poi_id": "poi789"
}

Unsubscribe Group POI Mutation

Description: Unsubscribes from updates related to a POI in a group.

mutation Unsubscribe_group_poi(
  $group_id: String, # ID of the group
  $poi_id: String # ID of the POI
) {
  unsubscribe_group_poi(
    group_id: $group_id,
    poi_id: $poi_id
  ) {
    status # Success or failure status
  }
}

# VARIABLES
{
  "group_id": "group123",
  "poi_id": "poi789"
}

Group Members Query

Description: Retrieves the members of a specific group, including their roles, status, and location details.

query getGroupMembers($user_id: String, $group_id: String) {
  user(user_id: $user_id) {
    engagement {
      groups(group_id: $group_id) {
        slice {
          members {
            slice {
              poi_subscriptions
              user_id
              role
              status
              status_expires_at
              joined_at
              last_known_location {
                latitude
                longitude
                timestamp
              }
              current_poi {
                poi_id
                poi_details {
                  name
                  coordinates {
                    latitude
                    longitude
                  }
                }
                entered_poi_at
              }
            }
          }
        }
      }
    }
  }
}

# VARIABLES
{
  "user_id": "xyz789",
  "group_id": "abc123"
}

Group Leaderboard Query

Description: Retrieves leaderboard details for a specific group, including user ranks and scores.

query getGroupLeaderboard($user_id: String, $group_id: String) {
  user(user_id: $user_id) {
    engagement {
      groups(group_id: $group_id) {
        slice {
          leaderboard {
            slice {
              user_id
              rank
              ranking_attr
              ranking_score
            }
          }
        }
      }
    }
  }
}

# VARIABLES
{
  "user_id": "xyz789",
  "group_id": "abc123"
}

Group Feed Query

Description: Retrieves the feed messages of a specific group.

query getGroupFeed($user_id: String, $group_id: String) {
  user(user_id: $user_id) {
    engagement {
      groups(group_id: $group_id) {
        slice {
          feed {
            slice {
              message
              params
            }
          }
        }
      }
    }
  }
}

# VARIABLES
{
  "user_id": "xyz789",
  "group_id": "abc123"
}

Group POIs Query

Description: Retrieves the points of interest (POIs) for a specific group.

query getGroupPOIs($user_id: String, $group_id: String) {
  user(user_id: $user_id) {
    engagement {
      groups(group_id: $group_id) {
        slice {
          points_of_interest {
            slice {
              poi_id
              poi_details {
                name
                coordinates {
                  latitude
                  longitude
                }
                address {
                  city
                }
              }
            }
          }
        }
      }
    }
  }
}

# VARIABLES
{
  "user_id": "xyz789",
  "group_id": "abc123"
}

Additional helpful links:

PreviousSocial GroupsNextAccessing Sentiance Insights

Last updated 7 months ago

definition

GQL