Описание AdWoW iOS SDK

  • Данный документ содержит базовый комплект описания работы с AdWoW iOS SDK. В качестве шаговой инструкции следует использовать «Руководство по интеграции AdWoW iOS SDK».

  • Для расширенной интеграции вам, возможно, будет полезно обратиться к документации AppleDocs. Если у вас есть вопросы, пожалуйста, свяжитесь с нами.

  • После регистрации вашего iOS приложения в Личном кабинете портала http://adwow.ru для вас будет сгенерирована пара ключей AppKey и SecretKey – эти два значения необходимы для инициализации главного объекта SDK. В большинстве случаев целесообразным является производить инициализацию внутри объекта, являющимся делегатом класса UIApplication (UIApplicationDelegate). Метод инициализации фреймворка принимает два параметра:

    @param appKey (NSString) : Ключ приложения (генерируется в Личном кабинете)
    @param appSecret (NSString ): Секретный ключ (генерируется в Личном кабинете)
    AdWow * adWow = [[AdWow sharedInstance] initWithAppKey:@”appKey” andSecret:@”appSecret”];
  • Главный объект фреймворка AdWoW предоставляет собой протокол AdWowDelegate, который позволяет осуществлять взаимодействие с ядром фреймворка, получая от него уведомления о различных событиях. Для этого необходимо объявить какой-либо класс своего приложения поддерживающим протокол AdWowDelegate и присвоить соответствующему свойству объекта adWow.delegate указатель на объект данного класса. Поскольку инициализация фреймворка производится внутри AppDelegate класса, то целесообразно назначить его ответственным за взаимодействие с фреймворком.

    @interface MyAppDelegate : UIResponder 
    AdWow * adWow = [[AdWow sharedInstance] initWithAppKey:@"appKey" andSecret:@"appSecret"];
    adWow.delegate = self;
  • Когда ваше приложение запускает сохранение момента с помощью SDK, он автоматически регистрируется в Личном кабинете. Очень важно корректно объявлять блок completionHandler, чтобы иметь возможность своевременно и адекватно реагировать на возникающие ошибки.

    Существует два метода сохранения моментов:

    Сохранить момент

    Принимает следующие параметры:@param momentName (NSString): Уникальный идентификатор момента. При обработке запроса в системе AdWoW будет автоматически создан |момент с указанным идентификатором для дальнейшего мониторинга. Данное значение определяется разработчиком (вами).@withCompletionHandler: Блок, вызываемый фреймфорком при завершении запроса. Необходим для показа рекламного объявления.

    [[AdWow sharedInstance] saveMoment:@"Level Z done" withCompletionHandler:^(AWUnit *unit, NSError *error) {
    if (error){
    NSLog( @"something's weird");
    }
    if (unit){
    [unit show];
    }
    }];

    Сохранить момент со значением

    Принимает следующие параметры:

    @param momentName (NSString): Уникальный идентификатор момента. При обработке запроса в системе AdWoW будет автоматически создан |момент с указанным идентификатором для дальнейшего мониторинга. Данное значение определяется разработчиком (вами).

    @param value (double): Данное значение анализируется системой AdWoW, и если оно больше или равно пороговому значению, заданному в |Личном кабинете для данного момента, то пользователю будет выдана награда.

    @withCompletionHandler: Блок, вызываемый фреймфорком при завершении запроса. Необходим для показа формы награды.

    [[AdWow sharedInstance] saveMoment:@"Shao Chin Destroyed" value:16.0 withCompletionHandler:^(AWUnit *unit, NSError *error) {
    if (error){
    NSLog( @"something's weird");
    }
    if (unit){
    [unit show];
    }
    }];
  • Объект AdWoW позволяет указывать информацию о пользователе без участия в данном процессе самого пользователя. Например, если вы уже ранее получали от пользователя email, вы можете присвоить его соответствующему свойству объекта AdWoW. Форма получения награды в этом случае уже будет содержать поле для ввода электронной почты, заполненное полученным ранее значением.

    Установка свойств объекта.

    AdWow *adWow = [AdWow sharedInstance];
    • Email

      @property (NSString) *userEmail Устанавливает email пользователя, что приводит к заполнению поля email в форме награды, демонстрируемой пользователю.

      adWow.userEmail = @"john@doe.com";
    • Пол

      @property (NSString) *userGender Данное поле указывает пол пользователя, что позволяет системе AdWoW подбирать наиболее релевантные награды.

      adWow.userGender = @"Male"
    • День рождения

      @property (NSDate) *userBirthday Данное поле указывает возраст пользователя, что позволяет системе AdWoW подбирать наиболее релевантные награды.

      adWow.userBirthday = @"03/16/1980";
  • Модуль – это специальная сущность для работы с модулем награды. Типичный жизненный цикл модуля: Вызов saveMoment -> Показ Модуля -> событие Форма награды показана -> событие Форма награды скрыта -> событие Модуль скрыт

  • AdWoW имеет возможность уведомлять ваше приложение при возникновении различных событий, таких, например, как показ и скрытие Уведомлений. При сохранении момента с помощью [AdWow sharedInstance] вы можете установить обработчики событий для следующих сущностей:

    • модули;
    • уведомления;
    • модальные формы

    Протокол AWUnitDelegate

    AWUnitDelegate является обобщенным способом доставки уведомлений о событиях в системе AdWoW. Делегат может быть установлен при вызове метода saveMoment.

    [[AdWow sharedInstance] saveMoment: momentName withCompletionHandler:^(AWUnit *unit){
    // установим делегат перед показом модуля
    unit.delegate = self;
    // показ модуля
    [unit show]
    }];

    В том же самом программном модуле необходимо реализовать соответствующие методы протокола. Пример реализации:

    - (void)willPresentUnit: (AWUnit *) unit {
    NSLog( @"Looking forward to see my unit");
    }

    Список методов протокола AWUnitDelegate

    willPresentUnit - вызывается перед тем, как модуль показывается пользователю.

    didDismissUnit - вызывается после того, как модуль скрывается.

    Нотификация AWNotification

    Данный класс реализует промежуточное представление награды. Представляет собой прямоугольную форму, всплывающую снизу или сверху экрана. После 5 секунд бездействия со стороны пользователя она исчезает. Если пользователь нажал на нотификацию, запускается загрузка модальной формы. Нотификация реализует протокол AWNotificationDelegate. Делегат может быть установлен при вызове метода saveMoment.

    [[AdWow sharedInstance] saveMoment: momentName withCompletionHandler:^(AWUnit *unit){
    // установим делегат перед показом модуля
    unit.notification.delegate = self;
    // показ модуля
    [unit show]
    }];

    В том же самом программном модуле необходимо реализовать соответствующие методы протокола. Пример реализации:

    - (void)willPresentNotification: (AWNotification *) notification{
    NSLog( @"Notification arrived");
    }

    Список методов протокола AWNotificationDelegate

    willPresentNotification - вызывается перед тем, как нотификация отображается на экране.

    didDismissNotification - вызывается, если нотификация скрывается после пятисекундного бездействия.

    didDismissNotificationWithClick - вызывается, если нотификация скрылась после того, как пользователь нажал на нотификацию и запустил процесс загрузки модальной формы.

    Модальные формы AWFormDelegate

    Объект AWForm представляет собой полноэкранную форму награды AdWow. Делегат может быть установлен при вызове метода saveMoment.

    [[AdWow sharedInstance] saveMoment: momentName withCompletionHandler:^(AWUnit *unit){
    // установим делегат формы перед показом модуля.
    AWForm *form = unit.form;
    form.delegate = self;
    // показ модуля
    [unit show]
    }];

    Как и в случае с обработчиками модуля или нотификации, обработчики формы необходимо реализовывать в том же программном модуле, в котором вызывается и метод сохранения момента.

    - (void)willPresentForm: (AWForm *) form {
    NSLog( @"Get ready for reward!");
    }

    Список методов протокола AWFormDelegate

    willPresentForm - вызывается перед тем, как модуль показывается пользователю

    didDismissForm - вызывается после того, как модуль скрывается либо путем кнопки Закрыть, либо в случае, если пользователь принял награду

  • AdWoW SDK позволяет подключать собственные стили для уведомлений, показываемых пользователю. Данный подход в значительной степени увеличивает совместимость внешнего стиля AdWoW с вашим приложением, а так же уровень.

    User Experience. Для отображения нотификации с индивидуальным стилем необходимо убедиться в отсутствии ошибок при сохранении момента. Следующий за проверкой на ошибки код реализует установку индивидуального стиля уведомления.

    // уже внутри completionHandler
    if (unit){
    // Устанавливаем координаты, размеры и другие свойства уведомления.
    AWNotificationView *notificationView = [[AWNotificationView alloc] initWithFrame:CGRectMake(0,0,320,50)];
    notificationView.backgroundColor = [[UIColor colorYouLike]];
    [AdWow sharedInstance].notificationView = notificationView
    // Теперь, когда объект notificationView создан и проинициазилирован, нужно создать объект самой нотификации, и присвоить его свойству объекта модуля
    AWNotification *notification = [AWNotification new];

    unit.notification = notification;
    // Создаем индивидуальный стиль уведомления
    UIView * customView ...
    // Встраиваем созданное представление в уведомление
    [notificationView addSubview: customView]
    // Запускаем показ уведомления
    notificationView.unit = unit;
    [unit show];
    }

    Примечание. Указанный способ создания индивидуальных уведомлений не является единственно возможным. Вы можете реализовать данную функциональность другим способом, на ваше усмотрение