Getting and displaying Events

Getting and displaying Events

In many cases, you'll want to display a list of events for your users to select one, or at the very least you'll want to fetch the data of a single event in order to contextualise the Elements the user is seeing.

While you may not always want to process the currently active Event, this is the most common approach to selecting which Event is the focal point. The snippet below illustrates how to retrieve the list of all available Events and identify one that is currently in the active state.

You can use the state of the Event to filter and locate the Event that suits your needs. There are three states an event can be in:

• Active: When the Event is currently live

• Upcoming: When the Event is available, but it's start date is in the future

• Finished: When the Event has concluded

iOS

func displayActiveEvent(in project: Project) {
      // If left unspecified, the `getEvents` function would use 
      // the project you setup in the SDK by calling `configure()`
      project.getEvents { result in
      do {
        let events = try result.get()
        
        // You can find an active event by checking it's state
        guard let firstActiveEvent = events.first(where: { $0.state == .active }) else {
          return
        }
        
        // You can fetch some of its properties
        // And display them in your UI as you see fit
        let id = firstActiveEvent.id
        let myField = firstActiveEvent.fields["my field"]
        let eventName = firstActiveEvent.name
        let eventFinishDate = firstActiveEvent.endAt
      } catch {
        // Treat the error
      }
    }
}

Android

fun displayActiveEvent(project: Project) {
    // If left unspecified, the `getEvents` function would use 
    // the project you setup in the SDK by calling `configure()`
    project.getEvents {
        it.onFailure {
            // Treat the error, `it` is a throwable
        }
        it.onSuccess {
            val firstActiveEvent = it.firstOrNull { it.state == EventState.ACTIVE }
            // You can fetch some of its properties
            // And display them in your UI as you see fit
            val id = firstActiveEvent?.id
            val myField = firstActiveEvent?.fields?.get("my field")
            val eventName = firstActiveEvent?.name
            val eventFinishDate = firstActiveEvent?.endAt
        }
    }
}

JavaScript

import { getEvents } from '@monterosa/sdk-interact-kit';

async function displayActiveEvent() {
  try {
    // If left unspecified, the `getEvents` function would use
    // the project you setup in the SDK by calling `configure()`
    const events = await getEvents();

    const firstActiveEvent =
      events.find(({ state }) => state === EventState.Active);

    const {
      id,
      name,
      endAt,
      fields: {
        my_field: eventCustomField,
      },
    } = firstActiveEvent;

    console.log(firstActiveEvent, eventCustomField);
  } catch (e) {
    console.error('Something went wrong!', e);
  }
}

getEvents will return the list of events sorted so that the most recent event is first, and the oldest is last

Additionally, you can be notified of any updates to the Event using this snippet:

iOS

class MyEventUpdateDelegate: EventUpdateDelegate {
    func didReceiveUpdate(event: Event) {
        // Called when the data in the event changes
    }
    
    func didChangeState(event: Event) {
        // Called when the state of the event changes
    }
    
    func didPublishElement(event: Event, element: Element) {
        // Called when an element is published
    }
    
    func didRevokeElement(event: Event, element: Element) {
        // Called when an element is revoked
    }
}

let myDelegate = MyEventUpdateDelegate()
event.add(listener: myDelegate)

// When we no longer need to be notified about event changes.
event.remove(listener: myDelegate)

Android

class MyEventUpdateListener : EventUpdateListener {
    override fun onEventUpdated(event: Event) {
        // Called when the data in the event changes
    }

    override fun onEventStateChanged(event: Event) {
        // Called when the state of the event changes
    }

    override fun onElementPublished(event: Event, element: Element) {
        // Called when an element is published
    }

    override fun onElementRevoked(event: Event, element: Element) {
        // Called when an element is revoked
    }
}

val myListener = MyEventUpdateListener()
event.add(myListener)

// When we no longer need to be notified about event changes.
event.remove(myListener)

JavaScript

import { 
  onElementPublished,
  onElementRevoked,
  onEventUpdated,
  onEventState,
} from '@monterosa/sdk-interact-kit';

// Called when an element is published to an event
const unsubscribeOnElementPublished = onElementPublished(event, 
    (element) => { console.log(element) }
);

// Called when an element is revoked from the event
const unsubscribeOnElementRevoked = onElementRevoked(
    event, 
    element => { console.log(element) }
);

// Called when the event is updated
const unsubscribeOnEventUpdated = onEventUpdated(
    event, 
    () => { console.log(event) }
);

// Called when the event state changes
const unsubscribeOnEventState = onEventState(
    event, 
    (state) => { console.log(state) }
);

Alternatively, you can also obtain the Event by its ID. This is useful if you want to attach a given known Event to specific information in your platform. For instance, you could create an Event for a given football match, and then link all the articles relevant to that match to the Event, so that you display match details, or interactive Elements relevant to that match within the article.

The following snippet showcases how to get an Event from an ID, which we'll assume in this case is being provided by your API.

JavaScript

import { getEvent } from "@monterosa/sdk-interact-kit";

const event = await getEvent('<event-id>'); // can be null