Class: Parse::Audience

Inherits:
Object show all
Defined in:
lib/parse/model/classes/audience.rb

Overview

Note:

_Audience is hardcoded master-key-only at Parse Server's REST layer (SharedRest.js). CLP changes via Object.set_clp have no effect — manage audiences from a master-key client or expose them through a Cloud Code function.

This class represents the data and columns contained in the standard Parse _Audience collection. Audiences are pre-defined groups of installations that can be targeted for push notifications. They store query constraints that define which installations belong to the audience.

Audiences are useful for:

  • Reusable push targets (e.g., "VIP Users", "Beta Testers")
  • A/B testing different user segments
  • Marketing campaigns to specific demographics

== Caching

Audience queries are cached by default to improve push notification performance. The cache has a configurable TTL (default: 5 minutes).

The default schema for the Audience class is as follows: class Parse::Audience < Parse::Object # See Parse::Object for inherited properties...

 property :name
 property :query, :object  # The Installation query constraints

end

Examples:

Configure cache TTL

Parse::Audience.cache_ttl = 600  # 10 minutes

Clear the cache

Parse::Audience.clear_cache!

Bypass cache for a specific lookup

audience = Parse::Audience.find_by_name("VIP Users", cache: false)

Creating an audience

audience = Parse::Audience.new(
  name: "iOS VIP Users",
  query: { "deviceType" => "ios", "vip" => true }
)
audience.save

Targeting an audience with push

Parse::Push.new
  .to_audience("iOS VIP Users")
  .with_alert("Exclusive offer!")
  .send!

See Also:

Constant Summary collapse

DEFAULT_CACHE_TTL =

Default cache TTL in seconds (5 minutes)

300

Constants inherited from Object

Object::BUILTIN_PARSE_CLASS_NAMES, Object::IDENTIFICATION_FIELDS, Object::VALID_ACL_POLICIES

Constants included from Core::Schema

Core::Schema::DEFAULT_PUBLIC_CLP, Core::Schema::SCHEMA_READONLY_CLASSES

Constants included from Core::Describe

Core::Describe::ALL_SECTIONS, Core::Describe::CORE_FIELD_KEYS, Core::Describe::LOCAL_SECTIONS, Core::Describe::NETWORK_SECTIONS

Constants included from Core::Indexing

Core::Indexing::INDEX_REGISTRY_MUTEX, Core::Indexing::MAX_INDEXES_PER_COLLECTION, Core::Indexing::PARSE_MANAGED_ARRAY_FIELDS, Core::Indexing::SENSITIVE_FIELDS

Constants included from Core::SearchIndexing

Core::SearchIndexing::ALLOWED_INDEX_TYPES, Core::SearchIndexing::INDEX_NAME_PATTERN

Constants included from Core::VectorSearchable

Core::VectorSearchable::VECTOR_VISIBILITY_MODES

Constants included from Core::Fetching

Core::Fetching::NON_SERIALIZABLE_IVARS

Constants included from Core::EmbedManaged

Core::EmbedManaged::WRITER_KEY

Constants included from Core::ParseReference

Core::ParseReference::OBJECT_ID_LENGTH, Core::ParseReference::SEPARATOR

Constants included from Core::FieldGuards

Core::FieldGuards::GUARD_MODES

Constants included from Properties

Properties::BASE, Properties::BASE_FIELD_MAP, Properties::BASE_KEYS, Properties::CORE_FIELDS, Properties::DELETE_OP, Properties::PROTECTED_INITIALIZE_KEYS, Properties::PROTECTED_MASS_ASSIGNMENT_KEYS, Properties::TYPES

Constants inherited from Pointer

Pointer::ATTRIBUTES, Pointer::OBJECT_ID_FORMAT

Constants inherited from Model

Model::CLASS_AUDIENCE, Model::CLASS_INSTALLATION, Model::CLASS_JOB_SCHEDULE, Model::CLASS_JOB_STATUS, Model::CLASS_PRODUCT, Model::CLASS_PUSH_STATUS, Model::CLASS_ROLE, Model::CLASS_SCHEMA, Model::CLASS_SESSION, Model::CLASS_USER, Model::ID, Model::KEY_CLASS_NAME, Model::KEY_CREATED_AT, Model::KEY_OBJECT_ID, Model::KEY_UPDATED_AT, Model::OBJECT_ID, Model::SYSTEM_CLASS_MAP, Model::TYPE_ACL, Model::TYPE_BYTES, Model::TYPE_DATE, Model::TYPE_FIELD, Model::TYPE_FILE, Model::TYPE_GEOPOINT, Model::TYPE_NUMBER, Model::TYPE_OBJECT, Model::TYPE_POINTER, Model::TYPE_POLYGON, Model::TYPE_RELATION

Class Attribute Summary collapse

Instance Attribute Summary collapse

Attributes inherited from Object

#acl, #created_at, #id, #updated_at

Attributes inherited from Pointer

#id, #parse_class

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Object

#[], #[]=, #__type, #_resolve_acl_owner_id, #_resolve_default_acl, #acl_changed?, acl_owner_field, acl_policy, acl_policy_setting, #acl_was, #acl_will_change!, #after_create, #after_destroy, #after_save, #after_update, #after_validation, #apply_defaults!, #around_create, #around_destroy, #around_save, #around_update, #around_validation, #as_json, #autofetch_disabled?, #before_create, #before_destroy, #before_save, #before_update, #before_validation, build, #changed, #changed?, class_permissions, #clear_attribute_change!, #clear_changes!, #clear_partial_fetch_state!, default_acls, describe_access, #disable_autofetch!, #enable_autofetch!, #existed?, fetch_clp, #fetched?, #fetched_keys, #fetched_keys=, #field_was_fetched?, #filter_for_user, filter_results_for_user, #fully_fetched?, #has?, #has_selective_keys?, #hybrid_ranks, #hybrid_score, #initialize, #keys, master_only_class!, #nested_fetched_keys, #nested_fetched_keys=, #nested_keys_for, #new?, #parse_class, #partially_fetched?, #persisted?, pointer, #pretty, private_acl!, protect_fields, #reload!, roles_for_user, #rollback!, #run_after_create_callbacks, #run_after_delete_callbacks, #run_after_save_callbacks, #run_before_create_callbacks, #run_before_save_callbacks, #schema, #search_highlights, #search_score, set_class_access, set_clp, set_default_acl, set_default_clp, set_read_user_fields, set_write_user_fields, #twin, unlistable_class!, update_clp!, #updates, #valid?, #validate!, #vector_score, wait_for, watch, webhook, webhook_function

Methods included from Core::Querying

#all, #all_as, #count, #count_distinct, #cursor, #distinct, #each, #find, #find_cached, #first, #first_as, #group_by, #group_by_date, #last_updated, #latest, #literal_where, #newest, #oldest, #pluralized_alias!, #scope, #subscribe

Methods included from Core::Schema

#_default_class_level_permissions_for_upgrade, #auto_upgrade!, #create_schema, #fetch_schema, #reset_clp!, #schema, #update_schema

Methods included from Core::Describe

#describe

Methods included from Core::Indexing

#apply_indexes!, #indexes_plan, #mongo_geo_index, #mongo_index, #mongo_index_declarations, #mongo_relation_index, #unique_index_on

Methods included from Core::SearchIndexing

#apply_search_indexes!, #mongo_search_index, #mongo_search_index_declarations, #search_indexes_plan

Methods included from Core::VectorSearchable

#find_similar, #hybrid_search, #vector_visibility, #vectors_public_by_default?

Methods included from Parse::Agent::MetadataDSL

#agent_description, #agent_methods, #property_descriptions, #property_enum_descriptions

Methods included from Core::Actions

#_deleted?, #change_requests, #changes_applied!, #changes_payload, #create, #destroy, #destroy_request, #op_add!, #op_add_relation!, #op_add_unique!, #op_destroy!, #op_increment!, #op_remove!, #op_remove_relation!, #operate_field!, #prepare_save!, #relation_change_operations, #save, #save!, #set_attributes!, #update, #update!, #update_relations, #uri_path

Methods included from Core::Fetching

#autofetch!, #fetch, #fetch!, #fetch_cache!, #fetch_json, #fetch_object, #prepare_for_dirty_tracking!

Methods included from Core::EmbedManaged

#compute_embedding!

Methods included from Parse::Associations::HasMany

has_many, #relation_changes?, #relation_updates, #relations

Methods included from Parse::Associations::BelongsTo

belongs_to, #key?

Methods included from Parse::Associations::HasOne

has_one

Methods included from Core::ParseReference

format, generate_object_id, parse

Methods included from Core::FieldGuards

#apply_field_guards!

Methods included from Properties

#apply_attributes!, #attribute_changes?, #attribute_updates, #attributes, #attributes=, #field_map, #fields, #format_operation

Methods inherited from Pointer

#==, #[], #[]=, #__type, #attributes, #className, #fetch, #fetch_cache!, #fetch_json, #fetch_object, #fetched?, #hash, #initialize, #json_hash, #method_missing, #pointer, #pointer?, #present?, #respond_to_missing?, #search_highlights, #search_score, #sig, #vector_score

Methods inherited from Model

#dirty?, find_class, same_parse_class?

Methods included from Client::Connectable

#client

Constructor Details

This class inherits a constructor from Parse::Object

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class Parse::Pointer

Class Attribute Details

.cache_ttl ⇒ Object 



70
71
72
 
# File 'lib/parse/model/classes/audience.rb', line 70

def cache_ttl
  @cache_ttl ||= DEFAULT_CACHE_TTL
end

Instance Attribute Details

#name ⇒ String

The display name of this audience.

Returns:

  • (String) —

    The audience name.



155
 
# File 'lib/parse/model/classes/audience.rb', line 155

property :name

#query ⇒ ActiveSupport::HashWithIndifferentAccess?

The query constraints as a Hash (decoded from the stored JSON string).

Returns:

  • (ActiveSupport::HashWithIndifferentAccess, nil) 


170
 
# File 'lib/parse/model/classes/audience.rb', line 170

property :query_json, :string, field: :query

Class Method Details

.cache_fetch(name, cache: true) ⇒ Parse::Audience?

Get an audience from cache or fetch from server

Parameters:

  • name (String) —

    the audience name

  • cache (Boolean) (defaults to: true) —

    whether to use cache (default: true)

Returns:



87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
 
# File 'lib/parse/model/classes/audience.rb', line 87

def cache_fetch(name, cache: true)
  return find_by_name_uncached(name) unless cache

  cache_mutex.synchronize do
    @audience_cache ||= {}
    @cache_timestamps ||= {}

    # Cleanup expired entries periodically to prevent memory growth
    cleanup_expired_cache_entries

    cached = @audience_cache[name]
    timestamp = @cache_timestamps[name]

    # Check if cache is valid
    if timestamp && (Time.now.to_i - timestamp) < cache_ttl
      return cached
    end

    # Fetch and cache (fetch happens inside lock - acceptable for short TTL cache)
    audience = find_by_name_uncached(name)
    @audience_cache[name] = audience
    @cache_timestamps[name] = Time.now.to_i

    audience
  end
end

.cache_mutex ⇒ Mutex

Thread-safe mutex for cache operations

Returns:

  • (Mutex) 


125
126
127
 
# File 'lib/parse/model/classes/audience.rb', line 125

def cache_mutex
  @cache_mutex ||= Mutex.new
end

.cleanup_expired_cache! ⇒ Integer

Remove expired entries from cache to prevent memory leaks Called automatically during cache_fetch, but can also be called manually

Returns:

  • (Integer) —

    number of entries removed



117
118
119
120
121
 
# File 'lib/parse/model/classes/audience.rb', line 117

def cleanup_expired_cache!
  cache_mutex.synchronize do
    cleanup_expired_cache_entries
  end
end

.clear_cache!

This method returns an undefined value.

Clear the audience cache



76
77
78
79
80
81
 
# File 'lib/parse/model/classes/audience.rb', line 76

def clear_cache!
  cache_mutex.synchronize do
    @audience_cache = {}
    @cache_timestamps = {}
  end
end

.find_by_name(name, cache: true) ⇒ Parse::Audience?

Find an audience by name (uses cache by default).

Examples:

audience = Parse::Audience.find_by_name("VIP Users")
audience = Parse::Audience.find_by_name("VIP Users", cache: false)  # Bypass cache

Parameters:

  • name (String) —

    the audience name

  • cache (Boolean) (defaults to: true) —

    whether to use cache (default: true)

Returns:



233
234
235
 
# File 'lib/parse/model/classes/audience.rb', line 233

def find_by_name(name, cache: true)
  cache_fetch(name, cache: cache)
end

.installation_count(audience_name) ⇒ Integer

Get the count of installations matching an audience's query.

Examples:

count = Parse::Audience.installation_count("VIP Users")

Parameters:

  • audience_name (String) —

    the audience name

Returns:

  • (Integer) —

    the count of matching installations

Raises:

  • (Parse::Push::AudienceNotFound) —

    if no audience exists with the given name. Previously returned 0 on miss, which was indistinguishable from "audience exists but matches nothing."



245
246
247
248
249
250
251
252
253
254
255
256
257
258
 
# File 'lib/parse/model/classes/audience.rb', line 245

def installation_count(audience_name)
  audience = find_by_name(audience_name)
  if audience.nil?
    raise Parse::Push::AudienceNotFound,
          "Audience '#{audience_name}' not found in _Audience collection"
  end
  return 0 unless audience.query.present?

  q = Parse::Installation.query
  audience.query.each do |key, value|
    q.where(key.to_sym => value)
  end
  q.count
end

.installations(audience_name) ⇒ Parse::Query

Get a query for installations matching an audience.

Examples:

installations = Parse::Audience.installations("VIP Users").all

Parameters:

  • audience_name (String) —

    the audience name

Returns:

Raises:

  • (Parse::Push::AudienceNotFound) —

    if no audience exists with the given name. Previously returned an unconstrained Installation query on miss, which silently elevated the result set from "matches this audience" to "every Installation" — the same fail-open footgun as Push#to_audience.



270
271
272
273
274
275
276
277
278
279
280
281
282
283
 
# File 'lib/parse/model/classes/audience.rb', line 270

def installations(audience_name)
  audience = find_by_name(audience_name)
  if audience.nil?
    raise Parse::Push::AudienceNotFound,
          "Audience '#{audience_name}' not found in _Audience collection"
  end
  q = Parse::Installation.query
  if audience.query.present?
    audience.query.each do |key, value|
      q.where(key.to_sym => value)
    end
  end
  q
end

Instance Method Details

#format_value(key, val, data_type = nil) ⇒ Object

JSON-encode a Hash/Array assigned to the query field before the :string property coercion runs. Every assignment path — query=, query_constraint=, mass-assignment via new(query:), and server hydration — funnels through format_value, so intercepting here (rather than the public setter, which mass-assignment bypasses) is the single reliable place to keep the wire value valid JSON ({"k":"v"}) instead of Ruby's Hash#to_s ({"k"=>"v"}). A String passed in (e.g. a row loaded from the server) falls through to the normal string coercion untouched.



180
181
182
183
184
185
 
# File 'lib/parse/model/classes/audience.rb', line 180

def format_value(key, val, data_type = nil)
  if key == :query_json && (val.is_a?(Hash) || val.is_a?(Array))
    return val.to_json
  end
  super
end

#installation_count ⇒ Integer

Get the count of installations matching this audience's query.

Examples:

audience = Parse::Audience.first
puts "#{audience.name} has #{audience.installation_count} members"

Returns:

  • (Integer) —

    the count of matching installations



291
292
293
294
295
296
297
298
299
 
# File 'lib/parse/model/classes/audience.rb', line 291

def installation_count
  return 0 unless query.present?

  q = Parse::Installation.query
  query.each do |key, value|
    q.where(key.to_sym => value)
  end
  q.count
end

#installations ⇒ Parse::Query

Get a query for installations matching this audience.

Examples:

audience.installations.each { |i| puts i.device_token }

Returns:



305
306
307
308
309
310
311
312
313
 
# File 'lib/parse/model/classes/audience.rb', line 305

def installations
  q = Parse::Installation.query
  if query.present?
    query.each do |key, value|
      q.where(key.to_sym => value)
    end
  end
  q
end

#query_constraint ⇒ Hash

Alias for query to match Parse Server naming conventions.

Returns:

  • (Hash) —

    The query constraint hash.



215
216
217
 
# File 'lib/parse/model/classes/audience.rb', line 215

def query_constraint
  query
end

#query_constraint=(constraints) ⇒ Object

Set the query constraint.

Parameters:

  • constraints (Hash) —

    The query constraint hash.



221
222
223
 
# File 'lib/parse/model/classes/audience.rb', line 221

def query_constraint=(constraints)
  self.query = constraints
end