Class: Forem::Segment

Inherits:
APIResource show all
Extended by:
APIOperations::Create, APIOperations::List, APIOperations::Retrieve
Includes:
APIOperations::Delete
Defined in:
lib/forem/resources/segment.rb

Overview

Represents a user segment used for targeted content delivery on Forem.

Audience segments for billboard targeting. The API only permits managing segments you create yourself.

Segments are named groups of users that can be targeted with specific billboards or other content. Admins can create and delete segments, list their members, and add or remove users from them. Managing segments requires an admin API key.

Available operations (via mixins):

- +List+     — GET /api/segments          (getSegments)
- +Create+   — POST /api/segments         (createSegment)
- +Retrieve+ — GET /api/segments/:id
- +Delete+   — instance-level delete (DELETE /api/segments/:id)

Segment Fields

  • id (Integer) — The segment ID
  • type_of (String) — Marks segment as manually managed
  • user_count (Integer) — Current number of users in the segment

Examples:

List all segments

segments = client.segments.list
segments.each { |s| puts s.id }

Create a segment (no params accepted — the API ignores anything passed)

segment = client.segments.create
#=> #<Forem::Segment id=14 type_of="manual">

List users in a segment

segment = client.segments.retrieve(5)
segment.users.auto_paging_each { |u| puts u.username }

See Also:

Constant Summary collapse

OBJECT_NAME = 
"segment"
RESOURCE_PATH = 
"/api/segments"

Instance Attribute Summary

Attributes inherited from ForemObject

#requestor

Instance Method Summary collapse

Methods included from APIOperations::Create

create

Methods included from APIOperations::List

list

Methods included from APIOperations::Retrieve

retrieve

Methods included from APIOperations::Delete

#delete, included

Methods inherited from APIResource

#refresh, resource_path, #resource_url

Methods inherited from ForemObject

#==, #[], #[]=, construct_from, cursor_list, #initialize, #inspect, #method_missing, paginated_list, #respond_to_missing?, #to_hash

Methods included from APIOperations::Request

included, #request

Constructor Details

This class inherits a constructor from Forem::ForemObject

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Forem::ForemObject

Instance Method Details

#add_users(params = {}, opts = {}) ⇒ ForemResponse

Add one or more users to this segment.

Add users in bulk. The response distinguishes successes (added) from failures (couldn't add).

Sends a PUT request to /api/segments/:id/add_users (addUsersToSegment).

Examples:

segment = client.segments.retrieve(5)
segment.add_users(user_ids: [101, 102, 103])

Parameters:

  • params (Hash) (defaults to: {}) —

    request body

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :user_ids (Array<Integer>) —

    list of user IDs to add

Returns:

See Also:



83
84
85
 
# File 'lib/forem/resources/segment.rb', line 83

def add_users(params = {}, opts = {})
  request(:put, "#{resource_url}/add_users", params, opts)
end

#remove_users(params = {}, opts = {}) ⇒ ForemResponse

Remove one or more users from this segment.

Sends a PUT request to /api/segments/:id/remove_users.

Examples:

segment = client.segments.retrieve(5)
segment.remove_users(user_ids: [101, 102])

Parameters:

  • params (Hash) (defaults to: {}) —

    request body

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :user_ids (Array<Integer>) —

    list of user IDs to remove

Returns:

See Also:



99
100
101
 
# File 'lib/forem/resources/segment.rb', line 99

def remove_users(params = {}, opts = {})
  request(:put, "#{resource_url}/remove_users", params, opts)
end

#users(params = {}, opts = {}) ⇒ Forem::ListObject<Forem::User>

Return the users who belong to this segment.

Returns users in this segment. Default: 30 per page, max: 1000.

Sends a GET request to /api/segments/:id/users (getUsersInSegment).

Examples:

segment = client.segments.retrieve(5)
segment.users.auto_paging_each { |u| puts u.username }

Parameters:

  • params (Hash) (defaults to: {}) —

    query parameters

  • opts (Hash) (defaults to: {}) —

    per-request options (e.g., :api_key)

Options Hash (params):

  • :page (Integer) —

    page number (default: 1)

  • :per_page (Integer) —

    number of results per page (default: 30, max: 1000)

Returns:

See Also:



62
63
64
65
66
 
# File 'lib/forem/resources/segment.rb', line 62

def users(params = {}, opts = {})
  opts = opts.dup
  opts[:requestor] ||= @requestor
  Forem::User.paginated_list("#{resource_url}/users", params, opts)
end