Latest 0.5.4
Homepage https://github.com/URXtech/urx-sdk-ios
License Apache 2.0
Platforms ios 6.0, requires ARC
Frameworks StoreKit, CoreLocation, UIKit, Foundation

URX iOS SDK

NOTE The URXSearch and URXWidgets integrations are deprecated. The new SDK is still hosted in this repository. Please see Migrating to the new URX SDK below.

The URX iOS SDK is a wrapper for URX’s Deep Link Search API.

To receive your API key, please visit dashboard.urx.com.

You can install urx-sdk-ios with CocoaPods, or as a static Framework. It’s up to you.

Migrating to the new URX SDK

URX is moving to a unified SDK repository. All code, frameworks and podspecs from URXWidgets are now available in this repository.

What does this mean?

You can still integrate URX with your App using CocoaPods, Frameworks or direct source integration. The existing CocoaPods are deprecated in favor of the new URX CocoaPod.

CocoaPods: Migrating to the URX CocoaPod

If you have integrated URXSearch only, then replace pod 'URXSearch' with pod 'URX/Search'.

If you have integrated URXWidgets only, then replace pod 'URXWidgets' with pod 'URX/Widgets'.

You can also integrate both subspecs using pod 'URX'.

Frameworks

The framework names have not changed. Use the directions below in `Setup using a Framework. Be sure to follow the directions for setting the -I flags in ‘Other C Flags’.

Setup with CocoaPods:

Step 1: Add a URX/Search subspec to your Podfile:

pod 'URX/Search'

Step 2: Install the URX/Search CocoaPod:

$ pod install

Step 3: Upgrading

You can always visit URX SDK to see the latest version.

Check for updates

$ pod search URX

Update to the latest version

$ pod update

Setup using a Framework:

Step 1: Add the URXSearch Framework to your Project:

First, clone this repository. Then, drag and drop the URXSearch.framework into the "Frameworks" directory of your project.

Step 2: Linking to URXSearch Binaries and Headers:

Make sure that the URXSearch.framework has been added to your project’s binary. In your project settings, select your Target and select the Build Phases tab. In the Link Binary With Libraries phase you should see URXSearch.framework. If not, hit the + button and select it from the list of options.

Step 3: Set up the API Key:

In order to use URX’s SDKs, you need to provide your API key. If you don’t already have one, visit URX.com to sign up today.

To add your API Key to your project, add a String row to your Info.plist file with URX API Key as the key and your API key as the value.

Step 4: Set -ObjC linker flag:

In your project’s Build Settings, make sure to add -ObjC in the "Other Linker Flags" setting.

Step 5: Set the -I flag:

In your project’s Build Settings, make sure to add -IURXSearch.framework/Headers in the "Other C Flags" setting.

Basic Usage:

Data from Search Results
#import "URX.h"

...

[[URXTerm termWithKeywords:@"ellie goulding"] searchAsynchronouslyWithSuccessHandler:^(URXSearchResponse *response) {
    // SEARCH SUCCESS HANDLER
    URXSearchResult *result = response.results[0];
    // The Search Result Content's Title
    NSLog(@"%@", result.name);
    // The Search Result Content's image url
    NSLog(@"%@", result.imageUrl);
    // The Search Result Content's longer text description
    NSLog(@"%@", result.descriptionText);
    // The Search Result Content's call to action text (ie. "Buy Tickets")
    NSLog(@"%@", result.callToActionText);
    // The Search Result Content's app name
    NSLog(@"%@", result.appName);
} andFailureHandler:^(URXAPIError *error) {
    // SEARCH FAILURE HANDLER
    NSLog(@"%@", error.errorMessage);
}];
Search & Resolve with App Store Fallback
#import "URX.h"

...

[[URXTerm termWithKeywords:@"ellie goulding"] searchAsynchronouslyWithSuccessHandler:^(URXSearchResponse *response) {
    // SEARCH SUCCESS HANDLER
    // Note: Integrations usually display the search result for the user
    // and set click handler to trigger resolving user to destination.
    // Resolve to the deeplink only if the app is installed,
    // otherwise fallback to the app store.
    [response.results[0] resolveAsynchronouslyWithAppStoreFallbackAndFailureHandler:^(URXAPIError *error) {
        NSLog(@"%@", error.errorMessage);
    }];
} andFailureHandler:^(URXAPIError *error) {
    // SEARCH FAILURE HANDLER
    NSLog(@"%@", error.errorMessage);
}];

Search Operators:

Basic Keyword Search
#import "URX.h"

...

[[URXTerm termWithKeywords:@"ellie goulding"] searchAsynchronouslyWithSuccessHandler:^(URXSearchResponse *response) {
    // SEARCH SUCCESS HANDLER
} andFailureHandler:^(URXAPIError *error) {
    // SEARCH FAILURE HANDLER
}];
Exact Phrase Match
#import "URX.h"

...

[[URXPhrase phraseWithString:@"ellie goulding"] searchAsynchronouslyWithSuccessHandler:^(URXSearchResponse *response) {
    // SEARCH SUCCESS HANDLER
} andFailureHandler:^(URXAPIError *error) {
    // SEARCH FAILURE HANDLER
}];
Filter by Action
#import "URX.h"

...

[[[URXTerm termWithKeywords:@"ellie goulding"] and:[URXActionFilter listenAction]] searchAsynchronouslyWithSuccessHandler:^(URXSearchResponse *response) {
    // SEARCH SUCCESS HANDLER
} andFailureHandler:^(URXAPIError *error) {
    // SEARCH FAILURE HANDLER
    NSLog(@"%@", error.errorMessage);
}];
Filter by Domain
#import "URX.h"

...

[[[URXTerm termWithKeywords:@"ellie goulding"] and:[URXDomainFilter domainWithPLD:@"spotify.com"]] searchAsynchronouslyWithSuccessHandler:^(URXSearchResponse *response) {
    // SEARCH SUCCESS HANDLER
} andFailureHandler:^(URXAPIError *error) {
    // SEARCH FAILURE HANDLER
    NSLog(@"%@", error.errorMessage);
}];
Geo Search
#import "URX.h"

...

[[[URXTerm termWithKeywords:@"ellie goulding"] and:[URXNearFilter nearLatitude:37.7811919 AndLongitude:-122.3950664]] searchAsynchronouslyWithSuccessHandler:^(URXSearchResponse *response) {
    // SEARCH SUCCESS HANDLER
} andFailureHandler:^(URXAPIError *error) {
    // SEARCH FAILURE HANDLER
    NSLog(@"%@", error.errorMessage);
}];

For more advanced boolean operations and complex queries, see the API Search Operators documentation.

Advanced Usage:

Search With Raw Query String
#import "URX.h"

...

[[URXRawQuery queryFromString:@"ellie goulding action:BuyAction near:"San Francisco""] searchAsynchronouslyWithSuccessHandler:^(URXSearchResponse *response) {
    // SEARCH SUCCESS HANDLER
} andFailureHandler:^(URXAPIError *error) {
    // SEARCH FAILURE HANDLER
}];
Search & Resolve with Web Fallback
#import "URX.h"

...

[[URXTerm termWithKeywords:@"ellie goulding"] searchAsynchronouslyWithSuccessHandler:^(URXSearchResponse *response) {
    // SEARCH SUCCESS HANDLER
    // Note: Integrations usually display the search result for the user
    // and set click handler to trigger resolving user to destination.
    // Resolve to the deeplink only if the app is installed,
    // otherwise fallback to the web page.
    [response.results[0] resolveAsynchronouslyWithWebFallbackAndFailureHandler:^(URXAPIError *error) {
        NSLog(@"%@", error.errorMessage);
    }];
} andFailureHandler:^(URXAPIError *error) {
    // SEARCH FAILURE HANDLER
    NSLog(@"%@", error.errorMessage);
}];
Resolve Url with App Store Fallback
#import "URX.h"

...

[[URXResolutionRequest requestFromUrl:@"http://www.spotify.com"] resolveAsynchronouslyWithAppStoreFallbackAndFailureHandler:^(URXAPIError *error) {
    // RESOLUTION FAILURE HANDLER
    NSLog(@"%@", error.errorMessage);
}];
Resolve Url with Web Fallback
#import "URX.h"

...

[[URXResolutionRequest requestFromUrl:@"http://www.spotify.com"] resolveAsynchronouslyWithWebFallbackAndFailureHandler:^(URXAPIError *error) {
    // RESOLUTION FAILURE HANDLER
    NSLog(@"%@", error.errorMessage);
}];
Resolve Url with Deferred Deeplink

NOTE You should take care to make sure only one of instance of resolveAsynchronouslyWithStoreKitFallbackAndFailureHandler: is active at a given time. You can ensure this by observing the URXResolutionResponseDidFinish notification, which is posted just before the operation completes.

#import "URX.h"

...

[[URXResolutionRequest requestFromUrl:@"http://www.spotify.com"] resolveAsynchronouslyWithStoreKitFallbackAndFailureHandler:^(URXAPIError *error) {
    // RESOLUTION FAILURE HANDLER
    NSLog(@"%@", error.errorMessage);
}];

You can cancel an deferred deeplink at any time. Note that cancelling the Deferred Deeplink will only cancel the deeplink–not a running app install.

[URXResolutionResponse cancelDeferredDeeplink];

Deferred Deeplink Configuration

There are a number of ways you can configure URXResolutionRequest’s Deferred Deeplink functionality:

Disable Automatic Loading Overlay Views:

NOTE If you disable the automatic loading views, you should be sure to observe the various URXResolutionResponse notifications and update your UI accordingly.

[URXSearch setShouldPresentLoadingViews:NO];
Deeplink Redirect Alert

This is a UIAlert that gets presented if the user navigates away from the SKStoreProductViewController before the app installation finishes.

// Customize the UIAlert Title
[URXSearch setDeeplinkAlertTitle:@"A Title"];
// Customize the UIAlert message
[URXSearch setDeeplinkAlertMessage:@"A Message"];
// Customize the UIAlert cancel button title
[URXSearch setDeeplinkAlertCancelButtonTitle:@"No Way!"];
// Customize the UIAlert confirm button title
[URXSearch setDeeplinkAlertConfirmButtonTitle:@"Take Me There!"];
Deferred Deeplink Notifications

Deferred Deeplinks posts a number of notifications to allow you to take appropriate action based on the install progress.

URXResolutionResponseWillStart

Posted when the app install starts.

URXResolutionResponseDidFinish

Posted when the app install finishes. If an error occurred, the userInfo dictionary will contain a URXResolutionResponseErrorKey key with an NSError object describing the error.

URXResolutionResponseWillLoadProductDetails

Posted before attempting to load product details from the app store.

URXResolutionResponseDidLoadProductDetails

Posted after the attempt to load product details from the app store completes. The userInfo dictionay will contain a URXResolutionResponseLoadAppDetailsSuccessKey which indicates whether or not the app details were loaded. If not, the deferred deeplink will fail and the error will be reported as part of the URXResolutionResponseDidFinish notification.

URXResolutionResponseWillPresentStore

Posted just before presenting the SKStoreProductViewController.

URXResolutionResponseDidPresentStore

Posted after presenting the SKStoreProductViewController.

URXResolutionResponseWillDismissStore

Posted just before dismissing the SKStoreProductViewController.

URXResolutionResponseDidDismissStore

Posted after dismissing the SKStoreProductViewController.

URXResolutionResponseWillLaunchDeepLink

Posted just before attempting to launch the Deferred Deeplink.
NOTE It’s possible for there to be a sizeable delay (several seconds) between when this notification is posted and when the app switch actually happens. For this reason, you should not depend on this notification for updating your UI. You should use this notification in conjuction with UIApplicationDidEnterBackgroundNotification.

iOS Widgets Framework

The URX iOS Widgets Framework is a collection of UI widgets to help you quickly integrate the URX App Search API into your app.

Setup using CocoaPods (iOS 8 and later)

You should not use CocoaPods for the Widgets framework if your iOS Deployment Target is iOS 7 or earlier. This framework requires dynamic framework support, which is only available in iOS 8. See CocoaPods Framework and Swift Support for details. Instead you should directly integrate the code into your project using Github. See "Setup Using Github" below.

Step 1: Install CocoaPods

Setup CocoaPods for your project if you haven’t done so already. See the Getting Started Guide for details.

Step 2: Add URXWidgets to your Podfile:

use_frameworks!
pod 'URX/Widgets'

Step 3: Install the URXWidgets CocoaPod:

$ pod install

Step 4: Set up the API Key

Before you can use the SDK, you must provide your URX API Key. To do this, add a String row to your Info.plist file with URX API Key as the key and your API key as the value. Contact [email protected] for an API key if you don’t already have one.

Upgrading using CocoaPods

Step 1: Check for updates

NOTE You can always visit URX SDK to see the latest version.

$ pod search URX

Step 2: Update to the latest version

$ pod update

Setup Using Github

Step 1: Clone the URXSearch respository:

$ git clone [email protected]:URXtech/urx-sdk-ios.git urx-sdk-ios

Step 2: Copy the Search and Widgets sources into your project

Copy the following folders into your project. Be sure to check ‘Copy items if needed’.

  • urx-sdk-ios/URXSearch
  • urx-sdk-ios/URXWidgets
  • urx-sdk-ios/URXWidgetsResources

Step 3: Set -I flag

In your project’s Build Settings add -I$(SRCROOT) in the "Other C Flags" setting.

Step 4: Set up the API Key

Before you can use the SDK, you must provide your URX API Key. To do this, add a String row to your Info.plist file with URX API Key as the key and your API key as the value. Contact [email protected] for an API key if you don’t already have one.

Setup using a Framework (Not recommended, does not support Xcode live rendering)

Step 1: Add the URXSearch and URXWidgets Frameworks to your Project

First, download the zip for the latest release tag. Then in Xcode, drag and drop the following frameworks into your project navigator to link the frameworks.

  • URXSearch.framework
  • URXWidgets.framework
  • URXWidgetsResources.framework

Step 2: Set up the API Key

Before you can use the SDK, you must provide your URX API Key. To do this, add a String row to your Info.plist file with URX API Key as the key and your API key as the value. Contact [email protected] for an API key if you don’t already have one.

Step 3: Set -ObjC linker flag

In your project’s Build Settings, make sure to add -ObjC in the "Other Linker Flags" setting.

Step 4: Set the -I flags:

In your project’s Build Settings, make sure to add -IURXSearch.framework/Headers and -IURXWidgets.framework/Headers in the "Other C Flags" setting.

License

Copyright 2014 URX

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Latest podspec

{
    "name": "URXSearch",
    "version": "0.5.4",
    "summary": "URX iOS SDK.",
    "authors": "URX",
    "homepage": "https://github.com/URXtech/urx-sdk-ios",
    "license": {
        "type": "Apache 2.0",
        "file": "LICENSE"
    },
    "platforms": {
        "ios": "6.0"
    },
    "source": {
        "git": "https://github.com/URXtech/urx-sdk-ios.git",
        "tag": "v0.5.4"
    },
    "source_files": [
        "URXSearch",
        "URXSearch/**/*.{h,m}"
    ],
    "public_header_files": "URXSearch/**/*.h",
    "frameworks": [
        "StoreKit",
        "CoreLocation",
        "UIKit",
        "Foundation"
    ],
    "requires_arc": true,
    "xcconfig": {
        "OTHER_LDFLAGS": "-lObjC"
    },
    "deprecated": true,
    "deprecated_in_favor_of": "URX/Search"
}

Pin It on Pinterest

Share This